Command-Line Interface

Stone ships as a single stone command. With no arguments it starts an interactive REPL.

Running Programs

stone run <file.stn>

Execute a Stone script using the WASM backend (default, fast iteration).

stone run main.stn
stone run main.stn --llvm
stone run main.stn --headless --quiet

stone build <file.stn>

Compile a Stone script to a target format.

stone build main.stn
stone build main.stn -t wasm -o main.wasm
stone build main.stn --optimize 3 --timings

stone check <file.stn>

Type-check a script without executing it.

stone check main.stn

Package Management

Stone uses Basin as its package registry. Packages are called Slabs.

stone init

Create a new package.son in the current directory.

stone install [package]

Install dependencies from package.son, or install a specific package.

stone install              # install all dependencies
stone install linalg       # install a specific slab
stone install -g linalg    # install globally

stone remove <package>

Remove a package. Alias: stone rm.

stone update [package]

Update all dependencies, or a specific package. Alias: stone up.

stone list

List installed packages. Alias: stone ls.

stone setup

Install the standard bundled Slabs globally (~/.stone/stone_modules/). This runs automatically on first use, but you can re-run it with --force to reinstall.

Extern Modules

Stone Slabs can include native C/C++ code as an extern kernel. The Stone wrapper files call into the compiled kernel via a naming convention — no manual FFI bindings needed.

How it works

1. Declare the extern module in package.son:

extern = {
  my_kernel = {
    type    = "c"
    sources = ["kernel/my_kernel.c"]
    deps = {
      some_lib = {
        wasm = { include = "include", lib = "lib", libs = ["mylib"] }
      }
    }
  }
}

1. Write .stn wrapper files that namespace-import _my_kernel and bind typed extern functions:

import _my_kernel as my_kernel

extern fn _my_add(a: num, b: num) -> num = my_kernel._my_add
extern fn _my_transform(shape: record, opts: record) -> record = my_kernel._my_transform

export fn add(a, b) = _my_add(a, b)
export fn transform(shape, opts) = _my_transform(shape, opts)

1. Implement the C functions with the stone_ prefix:

#include "stone_record_abi.h"

double stone_my_add(double a, double b) {
    return a + b;
}

StoneRecord* stone_my_transform(StoneRecord* shape, StoneRecord* opts) {
    // ...
}

1. Run stone extern build — it scans your .stn imports and C signatures to automatically derive the export list and compile via Emscripten.

Naming convention: _my_add in Stone maps to stone_my_add in C. Return types are auto-detected from C signatures (double → num, StoneRecord* → ptr).

stone extern build

Build the extern kernel to WASM.

External library dependencies are resolved via environment variables. For a dep named opencascade, set OPENCASCADE_WASM_ROOT to the path containing its WASM build (headers and static libs).

CLI Updates

stone upgrade

Update the Stone CLI to the latest version.

For details on the WASM and LLVM compilation backends, build targets, and the typical development workflow, see Backends.