Quickstart

Install and verify

Ryft 0.3 targets x64 Windows first. See installation for downloads and setup. Build prerequisites: Rust 1.89+, Cargo, Visual Studio C++ Build Tools and Windows SDK. Check rustc --version and cargo --version; from the repository run cargo build --release --locked. Use target/release/ryft.exe, or cargo install --path . --locked to add the compiler to your Cargo bin directory. Generated programs need no Rust toolchain.

ryft --help lists commands. Source files are UTF-8 and use .rz.

A console program

Save hello.rz:

fn add(a: i64, b: i64) -> i64 {
    return a + b;
}

fn main() {
    println("Hello from Ryft!");
    println(add(20, 22));
}

test addition {
    assert(add(20, 22) == 42);
}

ryft check hello.rz
ryft fmt hello.rz
ryft test hello.rz
ryft build hello.rz -o hello
.\hello.exe

check never invokes the backend. build compiles and links a native program; run does the same in a temporary directory and executes it. test compiles a test entry point and returns failure if any assertion fails.

An HTTP program

app api {
    base "/api";
    get "/hello/{name}" -> Json {
        return json({ "hello": param("name") });
    }
}

Build and run this file, then request /api/hello/Ryft. Define multiple apps in the same project to expose independent route sets from one binary. An HTTP project does not define global main; the runtime supplies it.

A persistent REST API

The catalog example implements authenticated create/list/read/delete operations. Set its declared environment capability:

$env:RYFT_API_TOKEN = 'replace-with-a-long-random-secret'
ryft build examples\rest_api\main.rz -o catalog
.\catalog.exe --port 8080 --data-dir .\catalog-data --isolate

From another terminal, set the same token and call the API:

$headers = @{ Authorization = "Bearer $env:RYFT_API_TOKEN" }
Invoke-RestMethod http://127.0.0.1:8080/api/products -Method Post -Headers $headers -ContentType application/json -Body '{"name":"Ryft mug"}'
Invoke-RestMethod http://127.0.0.1:8080/api/products -Headers $headers

The database is catalog-data/catalog/catalog.db. Restarting preserves data. Requests without the token receive 401; invalid input receives 400. SQL values are passed as bound parameters. The example creates its table lazily with CREATE TABLE IF NOT EXISTS; this is not a versioned migration framework. It uses one application API token, not user accounts or an identity provider. --isolate is Windows-only and starts app workers under committed-memory caps. Omit it for the single-process development runtime. Inspect /_ryft/health for worker readiness, PIDs, memory limits and restart counts. Restrict access to runtime health information at the ingress proxy.

Split a project into files

import "modules/math.rz";

fn main() {
    println(answer());
}

modules/math.rz:

fn answer() -> i64 {
    return 42;
}

Imports resolve relative to the importing file and must stay inside the entry file’s directory tree. A file imported twice is loaded once. Cycles are errors. Unaliased imports share one project namespace. Prefer aliases and public exports for new libraries: import "modules/math.rz" as math; and math::answer() with pub fn answer in the module. See modules and packages. App members remain private after merging.

Build controls

--emit-rust path.rs retains generated Rust for inspection. It depends on the manifest and lockfile in runtime/backend; it cannot be built directly with bare rustc. --target TRIPLE forwards a Rust target; cross compilation needs that target’s standard library, C compiler, and linker. Environment overrides: RYFT_CARGO, RYFT_RUSTC, RYFT_CACHE_DIR. The default backend cache is ryft-native-cache-v0.2 in the OS temporary directory. The build manifest uses locked dependencies and distinct generated binary names for concurrent builds.

ryft.toml selects project.entry when a command omits its source from the project directory. Local dependencies require ryft lock; see CLI reference.