Rust Backend

Build the study-plan package into a native executable, then run it from outside the source folder. The result runs on the OS and architecture it was built for without installing Topaz or Cargo there.

Prepare the package

Complete First Application, including topaz.toml, topaz.lock, and tests/plan.tpz. Install a compatible Rust toolchain with Cargo on the build machine. Run this page’s commands from study-plan.

The default compiler is written in Topaz. It generates Rust code, and Cargo builds the executable. You keep writing the application in Topaz syntax.

Keep the same application source

Use the two modules from First Application. The first is src/plan.tpz.

export record StudyTask {
    title: string,
    minutes: int,
    done: bool = false,
}

function parseMinutes(text: string) -> Result<int, string> {
    match toInt(text) {
        case Some(value) if value > 0 => Ok(value)
        case _ => Err("minutes must be a positive integer")
    }
}

export function makeTask(
    title: string,
    minuteText: string,
    done: bool = false,
) -> Result<StudyTask, string> {
    let minutes = parseMinutes(minuteText)?
    Ok(StudyTask { title: title, minutes: minutes, done: done })
}

export function summarize(tasks: Array<StudyTask>) -> string {
    let mut remaining = 0
    for task in tasks {
        if !task.done {
            remaining = remaining + task.minutes
        }
    }
    "tasks={tasks.length}, remaining={remaining} minutes"
}

Save the entry module as src/main.tpz.

import src.plan { StudyTask, makeTask, summarize }

export function main(args: Array<string>, stdin: string) -> Result<int, string> {
    let tasks: Array<StudyTask> = [
        makeTask("Run first program", "10", true)?,
        makeTask("Build application", "25", false)?,
    ]
    print(summarize(tasks))
    Ok(0)
}

Check and run before building

Check the package, run its selected test, and record the program output.

topaz check --root . --locked
topaz test tests/plan.tpz --root . --locked
topaz run --root . --locked

The check exits with code 0. The test reports tests/plan.tpz: test-ok. Running the package prints the following line.

tasks=2, remaining=25 minutes

For a diagnostic, fix the reported source line. For a failing test, compare its expected result in tests/plan.tpz with src/plan.tpz. If --locked reports changed package settings, review topaz.toml and update the lock as described in Packages & Distribution.

Inspect source or build an executable

To inspect or integrate the generated Cargo source files, use emit.

topaz emit --target rust --root . --locked --out-dir ../dist/rust-source

This writes the generated Rust source and its runtime files to ../dist/rust-source. To create the executable for deployment, use build.

topaz build --target native --root . --locked --out-dir ../dist/native

rust is the source-generation target for emit. The executable target for build is native, so build --target rust is rejected.

Inspect the output folder

The default debug build writes the following files.

dist/native/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── target
│   └── debug
│       └── program[.exe]
└── topaz-artifact.json

topaz-artifact.json lists the native target, required OS and architecture, build invocation, and each managed file’s size and SHA-256 hash. Topaz writes it last. A rebuild rejects modified managed files, unsafe path collisions, or a different target in the same folder. See Artifacts & Deployment for recovery and files to keep together.

Run outside the source folder

dist is outside study-plan. Choose another name if source-unavailable already exists, then rename the package and run the built program.

cd ..
mv study-plan source-unavailable
./dist/native/target/debug/program

In PowerShell, use Rename-Item study-plan source-unavailable to rename it and .\dist\native\target\debug\program.exe to run. The program prints tasks=2, remaining=25 minutes and exits with code 0. The source remains available in source-unavailable for later edits.

Resolve build and deployment problems

Integrate generated code

Keep application changes in .tpz source because generated Rust and its runtime files can be replaced by regeneration. They provide neither a stable manual extension API nor source-level Rust FFI. Test any wrapper you write for its own host behavior and permissions. After integration, compare the program output and exit code on the target you use.

For a Lispex decision application, complete Run Lispex Rules before building. All five native release targets support that application. Other build targets reject its Lispex profile before writing artifacts. Existing Topaz 5.18 packages use the embedded-core compatibility profile.

Continue with Interop Boundaries, Interpreter & Backends, or Artifacts & Deployment.