>docsplaygroundgithubdeploy

Native Backend

Choose between the Rust and Cranelift backends when compiling to native.

When compiling Tish to a native binary (tish build --target native), you can select the native backend with --native-backend.

Backends

BackendFlagNative importsWhat it actually produces
rust--native-backend rust (default)✅ SupportedRust source (via tish_compile) linked against tishlang_runtime — cargo builds the final binary
cranelift--native-backend cranelift❌ Not supportedSerialized bytecode embedded in the binary; executable runs tishlang_vm at startup (not CLIF lowering of opcodes)
llvm--native-backend llvm❌ Not supportedSame embedded-bytecode + tishlang_vm pattern as cranelift, linked via clang instead of the Cranelift object builder

When to use each

Rust backend (default)

The Rust backend transpiles your Tish program to Rust source calling tishlang_runtime — dynamic operations on Value — then invokes cargo build --release. This gives:

  • Full native-module support (import { Egui } from 'tish:egui', @scope/pkg)
  • Access to the full Rust ecosystem
  • Destructuring in function parameters
tish build main.tish -o app
# or explicitly:
tish build main.tish -o app --native-backend rust

Primitive lowering (in progress): Where types are annotated or can be inferred, the Rust backend emits native Rust primitives (f64, Vec<f64>, direct arithmetic) instead of Value. See Type Annotations for the current status.

Cranelift backend

The Cranelift backend produces a standalone binary without a cargo invocation — build is fast. However, the binary runs the same tishlang_vm on embedded bytecode; it is not AOT machine-code compilation of Tish opcodes. Throughput is VM-class, similar to tish run --backend vm.

Use when your program:

  • Has no native imports (pure Tish + file imports only)
  • Benefits from a fast build (no cargo + rustc overhead)
  • Does not need tish:* or @scope/pkg modules
tish build main.tish -o app --native-backend cranelift

If your program uses native imports, the Cranelift backend will error:

Cranelift backend does not support native imports (tish:*, @scope/pkg). Use --native-backend rust.

Known limitations (Cranelift / LLVM)

Because the binary runs tishlang_vm, any construct the VM supports is supported; constructs not yet implemented in the VM (e.g. certain destructuring patterns) are equally unsupported here. Destructuring parameters are not supported in bytecode — use the Rust backend or destructure inside the function body.

Target and feature flags

--native-backend applies only when --target native (the default). Other targets (js, wasm, wasi) ignore it.

For WebAssembly targets, see WASM Targets.

Feature flags (--feature http, etc.) apply to the Rust backend when compiling to native; the Cranelift/LLVM paths support only pure Tish.

Improve this documentation