Command line

stone [FILE [-- ARGS...]] [COMMAND]

run, build, and check read one .stn file, the entry file, along with every module it uses (see Modules), then checks them before doing anything else. Inside a project, the entry file need not be named (see Projects and their entry file). If the checker finds errors, the command prints all of them and exits with status 1 without running anything. Errors print as file:line:col: error[E0005]: message, followed by the source line and a caret under the problem. The code in brackets names the kind of error, which stone explain E0005 describes at length (see Error codes); runtime errors print as file:line:col: error: message, without one.

A program with a stone.toml next to its entry file uses packages (see Using packages). run, build, check, and test first download any package the program uses that is not downloaded yet, unless given --offline, which uses only what is already in the package store and never connects to anything.

Projects and their entry file

A project is a directory holding a stone.toml that names it (see Using packages), and every .stn file under it is one of its modules, found from that directory. A program’s entry file, where it starts running, is always the project’s main.stn. A library has a lib.stn instead, the module a program gets from use of the library’s name, and nothing to run. stone init makes either.

stone run, stone build, and stone check find the entry file themselves:

  • Given a file, as in stone run tools/sum.stn, they use that file, which may be any .stn file, inside a project or not. A program of one file needs no project.

  • Given a directory, as in stone run app, they use its main.stn. stone check takes a library’s lib.stn too.

  • Given nothing, they use the project the current directory is in: the nearest directory, the current one or any above it, that holds a stone.toml or a main.stn. So stone run works from anywhere inside a project, and errors and the build directory read as if the entry had been named, as in ../main.stn:3:7: error: .... Outside any project, it is an error that suggests stone init.

stone test, stone clean, stone fetch, stone tree, stone add, and stone remove find the project the same way when given no path.

stone init [PATH] [--lib] [--name NAME] [--no-git]

Starts a project in PATH, by default the current directory, making the directory if there is none:

hello/
  stone.toml    [package] with the name, version 0.1.0, and this stone's version as the oldest
  main.stn      a function, a line printing what it gives, and a test block for `stone test`
  .gitignore    build/

The package is named after the directory, with each - written as _ (my-app is my_app), unless --name gives the name, which must be a stone name. --lib starts a library: lib.stn holds a pub fn and a test block, and its name cannot be one a builtin module, the prelude, or a builtin takes, since programs use the library under it. An existing .gitignore is kept, gaining a build/ line if it has none. stone init refuses a directory that already holds a stone.toml, stone.lock, main.stn, or lib.stn, and then writes nothing.

When git is installed and the directory is not inside a git repository already, stone init also makes it one with git init. --no-git leaves it alone.

stone init hello && cd hello && stone run   # prints Hello, world!
stone init --lib --name csv

stone run [--offline] [FILE] [-- ARGS...]

Interprets the program: FILE, the main.stn of a directory, or the program the current directory is in (see Projects and their entry file). stone FILE is shorthand for stone run FILE. Everything after -- is passed to the program, which reads it with args(), even arguments that start with -, and an argument after the file without -- is an error. The program’s standard input is stone’s own, for input() and eof().

stone run examples/basics.stn
stone run sum.stn -- 1 2 3 < numbers.txt
stone run                                  # the project's main.stn
stone run -- --verbose input.txt           # the same, with two arguments

stone build [FILE...] [-o OUTPUT] [--target TARGET]... [--no-gpu] [--windows-gui] [--offline]

Compiles each program (each file, each directory’s main.stn, or with neither the program the current directory is in) to a native executable in its build directory (see Where executables go), writing the assembly next to it with a .s extension. stone assembles and links the program itself, so no assembler, linker, or C compiler needs to be installed. A Linux executable is a static program that needs no C library, so it runs on any Linux machine with the same processor. A macOS executable calls the system only through libSystem, which every Mac has, and is signed, as macOS requires, so it runs on any Apple silicon Mac with macOS 12 or later. Either has a symbol table, so tools such as gdb, lldb, perf, and objdump show its functions by name, such as fn.area for a stone function area and main for the top-level code. A Windows executable is a console program that imports only from the system’s own kernel32.dll and bcrypt.dll (and, for a program that opens windows with the gui module, user32.dll, gdi32.dll, and dwmapi.dll), so it runs on any x86-64 Windows 10 or 11 machine; windows need Windows 10 version 1703 or later. The net module and os.run are not supported there yet, so building a program that uses them for Windows is an error, and so is running or checking one on Windows.

A build for the machine stone runs on finds its NVIDIA GPU by itself and writes kernels for it: each piece of arithmetic on whole lists, such as a * 2.0 + b, becomes a kernel, and the kernels go next to the executable in a PTX file named after it and the GPU (build/basics.sm_75.ptx). It asks nvidia-smi (or the program STONE_NVIDIA_SMI names) for the first GPU, and measures that GPU once, by building and running a tiny program of its own: how long a launch takes and how fast lists move to the GPU and back. It keeps what it found in gpu/ under stone’s home directory (STONE_HOME, else ~/.stone, or %LOCALAPPDATA%\stone on Windows), one file per GPU, driver version, version of stone, and target, so later builds only ask nvidia-smi, and says so the one time it measures:

$ stone build saxpy.stn
note: measured the GPU, Quadro T1000 (sm_75), to decide where arithmetic on lists runs; later builds reuse it
Compiled build/saxpy

The executable carries the measurements and, for each kernel, the shortest list worth a launch, so it knows from its first instruction which arithmetic to send to the GPU, and a program whose lists are all short never starts the GPU’s driver. Run on a GPU of another compute capability, it measures that GPU when it first launches a kernel. A program with no arithmetic on lists has no GPU code.

A build carries no GPU code at all with --no-gpu, for a target other than this machine (such as --target x86_64-linux from Windows; another level of the same processor still counts as this machine), for macOS, or when there is no usable GPU: no nvidia-smi, a GPU older than sm_50, a measurement that fails (note: no GPU code: NVIDIA's driver is missing or unsupported, kept like a measurement when it will not change), or, on Linux, no /dev/nvidiactl (as under WSL) or no ptxas (note: no GPU code: cannot run 'ptxas' ...), since Linux executables need machine code. The STONE_GPU_DEVICES environment variable names the GPUs to write kernels for instead, separated by commas (STONE_GPU_DEVICES=sm_75,sm_90, or empty for none), for any target; such a program measures its GPU when it first launches a kernel. Only NVIDIA GPUs from sm_50 to sm_120 are supported, so naming an AMD GPU such as gfx1100 is an error.

With NVIDIA’s ptxas on PATH (or named by the STONE_PTXAS environment variable) the kernels are also compiled to machine code beside the PTX (build/basics.sm_75.cubin); a ptxas that rejects the kernels is an error. Without one, a build for GPUs STONE_GPU_DEVICES names warns and goes on.

A Windows executable with GPU code runs its kernels on an NVIDIA GPU. It carries the PTX for every GPU it was built for, and the machine code when ptxas made it. When it first launches a kernel, it loads NVIDIA’s driver, nvcuda.dll, from the system directory and picks code for the machine’s first GPU: machine code made for a GPU of the same generation that is not newer than it, or else the newest PTX that is not newer than it, which the driver compiles. If nothing fits, or there is no driver or GPU, it computes everything on the processor, so the executable runs on any machine. The results are the same either way, and a zero divisor is still reported at the element and position stone run reports.

The STONE_GPU environment variable changes this when the program runs: off computes everything on the processor, always launches every kernel whatever the length of its lists (a program otherwise launches only lists long enough to repay reaching the GPU), and require does as always but makes a program that cannot use the GPU stop with an error at the arithmetic instead, such as no GPU ran this program's kernels: nvcuda.dll is missing or too old, there is no CUDA device, it has no code for compute capability 8.6, or CUDA error 2.

With STONE_GPU_SIMULATE set, a build for Linux or Windows with GPU code (from STONE_GPU_DEVICES or this machine’s GPU) makes a program whose GPU is simulated: it computes each kernel on the processor, as the GPU would, from a description the build carries, so tests reach every path a launch takes on a machine without a GPU.

A Linux executable with GPU code runs the machine code ptxas made on an NVIDIA GPU too, on x86-64 and arm64, without libcuda or any other library: it speaks to NVIDIA’s kernel driver through /dev/nvidiactl and /dev/nvidia0 itself. So far it knows the interface of driver version 595 and the GPUs of the Ampere (sm_86) and Ada (sm_89) generations; on any other driver or GPU, or without machine code for the GPU, it computes on the processor, and under STONE_GPU=require stops with an error such as NVIDIA's driver is missing or unsupported. macOS executables carry no GPU code, so they compute everything on the processor. See Running code on the GPU to set this up.

--windows-gui builds Windows executables as programs with windows rather than console programs, so opening one from Explorer opens no console beside its window. Such a program has no console at all: what it prints goes nowhere unless its output is redirected, and input() finds the input already over. It needs a Windows target, either through --target or as the machine stone runs on, and changes nothing for the other targets of the same build.

The executable is for the machine stone runs on: x86-64 or arm64 Linux, arm64 macOS, or x86-64 Windows. --target picks one explicitly, and works the same from any machine. Give it more than once to build for several targets in one run:

target

runs on

x86_64-linux (or x86_64, x64)

x86-64 Linux

aarch64-linux (or aarch64, arm64)

arm64 Linux

aarch64-macos (or arm64-macos)

arm64 macOS

x86_64-windows (or x64-windows)

x86-64 Windows

A target is named <arch>[<level>]-<system>. There is no vendor or C library part, since compiled programs use no C library, but Rust’s names for the same machines work too, such as x86_64-unknown-linux-musl, aarch64-apple-darwin, and x86_64-pc-windows-msvc. A system left out means Linux.

The optional level names the processor features the program may assume: v1 to v4 for x86-64 (the x86-64 psABI levels, so x86_64v3-linux assumes AVX2), and v8, v8.1 to v8.9, v9, or v9.1 to v9.5 for arm64 (as in aarch64v8.2-macos). Without one, the program runs on every processor of the architecture. Arithmetic on whole lists works on two elements at a time with SSE2 or NEON at the baseline, four with AVX2 at x86-64 v3, eight with AVX-512 at v4 (the last few under a mask), and on Linux at arm64 v9 and above as many as the processor’s SVE vectors hold; AVX-512 and SVE also multiply ints in vectors. macOS uses NEON at every level, since Apple’s Armv9 processors have no SVE. math.floor uses roundsd from x86-64 v2, and the runtime uses BMI2 and LZCNT from v3. A program built for an x86-64 level above v1 first checks that the processor has every feature of the level, and otherwise stops before running anything, with error: this program needs an x86-64 v3 processor (naming its level) and exit status 1. A Linux program built for arm64 v9 or later checks for SVE and SVE2 the same way, with error: this program needs an aarch64 v9 processor with SVE2.

stone build examples/basics.stn
./examples/build/basics
stone build examples/basics.stn --target aarch64-linux --target aarch64-macos

The release archives use the same names for the machines the stone binary itself runs on, such as stone-x86_64-linux.tar.gz and stone-x86_64-windows.zip, plus stone-x86_64-macos.tar.gz for Intel Macs, where stone runs programs and builds them for the other targets, but cannot build programs for Intel Macs, so a build there needs --target.

The executable reads its own arguments and standard input the same way, so ./build/sum 1 2 3 behaves like stone run sum.stn -- 1 2 3.

Where executables go

Like Cargo’s target directory, each program has a build directory next to its entry file, the same directory its modules are found from, so the result does not depend on where you run stone:

examples/
  basics.stn
  build/
    basics              built for this machine
    basics.s
    aarch64-macos/
      basics            built with --target aarch64-macos
      basics.s
  • An executable is named after its entry file, so basics.stn becomes basics (basics.exe for Windows). A main.stn is named after its package instead, the name its stone.toml gives, so a project my-app that stone init made builds my-app/build/my_app. Without a stone.toml naming one, a main.stn is named after its directory, as a program of several files usually is, so geometry/main.stn becomes geometry/build/geometry.

  • An executable for the machine stone runs on goes straight into build/, and one for any other target into build/TARGET/, named as --target names it (aarch64-macos, x86_64v3-linux). Builds for different targets never overwrite each other.

  • Several files, as in stone build a.stn b.stn, each build into their own executable. If one has errors, stone prints them, still builds the rest, and exits with status 1.

  • -o OUTPUT writes the executable to exactly OUTPUT instead, with the assembly beside it with a .s extension, so it needs exactly one file and one target. A Windows executable is written to OUTPUT as given, so name it something.exe to run it by name there.

stone marks each build directory it makes with a .stone file, which stone clean looks for.

stone clean [PATH]

Removes the build directory of the program in PATH, which is an entry file or a directory and defaults to the program the current directory is in (or the current directory, in none). It only removes a build directory that stone build made; any other is an error and stays as it is.

stone clean examples/basics.stn   # removes examples/build
stone clean                      # removes the current project's build

stone check [--offline] [FILE] [--deny warnings]

Reports every syntax and type error without running the program (FILE, a directory’s main.stn or lib.stn, or the program the current directory is in), and exits with status 1 if there are any. Warnings alone print but leave the status at 0, unless --deny warnings reports each as an error, so that CI fails on any. Each kind of warning is a lint, whose id a warning shows, as in warning[W0004], and whose level a [lints] table in stone.toml sets.

check also warns about everything the program defines but never uses: variables that are assigned but never read, parameters, functions, methods, structs, enums, traits, and imports. stone run and stone build leave these out, so a program you are still writing runs quietly. A name that starts with _ is never reported, which is how to keep one on purpose, as in for _ in range(3): or fn handle(_event: str):. Some things are never reported:

  • pub definitions and the methods of a pub struct, which other modules may use.

  • The functions of a trait and of an impl Trait for T block, and their parameters, whose signatures the trait fixes.

  • A function that only calls itself is reported, but a function that only an unused function calls is reported only once that caller is gone.

main.stn:3:17: warning[W0001]: parameter 'h' is never used; remove it or name it '_h'
stone check examples/basics.stn
stone check --deny warnings

stone explain CODE

Explains the kind of error a code names, such as E0005 in main.stn:3:9: error[E0005]: expected int, found str: what it means, then a program that fails with it and the same program fixed. check, run, and build end their errors with a line naming the command, as in For more about this error, try `stone explain E0005`. Error codes lists every code. A lint’s id, such as W0004, or its name, such as lost_change, explains the lint, with a program that gets the warning and the same program fixed; Lints lists every lint. An unknown code is an error that names the closest one.

stone explain E0005
stone explain lost_change

stone test [PATH...] [--build] [--filter TEXT] [-j N] [--offline]

Runs the test blocks (test "description":) of every file of PATH that has any, every such file under a directory, and with no path those under the program the current directory is in (or the current directory, in none; see Testing). Each file is checked as part of the program it belongs to, the nearest directory at or above it with a main.stn or a stone.toml. Each test runs alone, without the file’s top-level statements, with no arguments and empty input, and passes if it ends without a runtime error (os.exit(0) included). What a failing test printed is shown with its error; a passing test’s output is not.

The report lists each file and its tests as ok or FAILED, then every failure, then a count such as 3 passed, 1 failed in 2 files. The status is 1 if a test failed or a file has errors. With nothing to run, it prints no tests found and the status is 0.

--build compiles each file into an executable under build/test/ in its program’s directory (build/test/geo/shapes for geo/shapes.stn) and runs each test as a run of it, instead of interpreting it. --filter runs only the tests whose description contains TEXT. -j tests N files at once, one per processor by default; a file’s tests run one after another.

stone test
stone test geo --filter "area"
stone test --build

stone add PACKAGE [--name NAME] [--host HOST]

Adds a package from a GitHub or GitLab release to the program the current directory is in: it finds the release, downloads it with every package it uses, names it under [dependencies] in stone.toml (making the file if there is none), and updates stone.lock. PACKAGE is github:owner/repo, gitlab:group/project, or a link to either, optionally followed by @latest (the default, the newest release that is not a pre-release), @1.2 (the newest 1.2.x), or an exact version such as @1.2.3. The dependency is named by the package’s own name unless --name gives another, and --host names a GitLab of your own, such as gitlab.example.com. Adding a package that is already there changes its version to the one found.

stone add github:alice/stone-json
stone add gitlab:bob/num@0.3 --name numbers

stone remove NAME

Removes the dependency NAME from the stone.toml of the program the current directory is in, and from stone.lock along with any package only it used. The downloaded files stay in the package store.

stone fetch [PATH] [--locked]

Downloads every package the program in PATH (an entry file or a directory, by default the program the current directory is in) uses, and brings its stone.lock up to date. With --locked, it fails if stone.lock would change instead of changing it, so CI builds only what was locked.

stone tree [PATH]

Prints the packages the program in PATH uses, each with its version and source, and below each the packages it uses in turn. A package used under a name other than its own shows as name = package, and one that appears again is marked (*) and not expanded again.

app
└── json 1.2.0 (github:alice/stone-json)
    └── num 0.3.0 (github:bob/num)

stone fmt [PATH...] [--check]

Rewrites files in stone’s one standard layout. A PATH is a file, or a directory, in which every .stn file below it is formatted, skipping hidden directories and build directories that stone build made; with no PATH, it formats the current directory. - formats standard input and writes the result to standard output.

Formatting only changes whitespace, never the code itself:

  • Each block is indented by four spaces, and tabs become spaces.

  • Operators take a space on each side (a + b, x = 1, a == b and c), and commas a space after them; brackets take none inside them (f(a, b), [1, 2], xs[0]).

  • A - before a value takes no space (-x, xs[:-1]), and neither does a field’s value in a struct (Point(x=1.0, y=-2.0)), the : of a slice (xs[1:n]), or a ? (f()?).

  • A : takes a space after it everywhere else (n: int, {"a": 1}, fn f[T: ord]), and -> one on each side.

  • Values inside a string are spaced like code ("{x + 1}"), while the string’s text, and every literal’s spelling (1e3, "\x41"), stays as written.

  • Comments stay, a comment after code following it by one space. A comment on a line of its own is indented like the block it sits in.

  • Runs of blank lines become one, and a blank line right after a line that opens a block, or at the start or end of the file, is removed. Trailing whitespace goes, and the file ends with one newline.

Since every statement is one line, stone never moves code from one line to another.

A file that does not parse is left alone: stone prints its errors, formats the other files, and exits with status 1. Types are not checked, so a file with type errors is formatted. With --check, nothing is written; stone lists each file that is not formatted and exits with status 1 if there is one, which suits continuous integration.

stone fmt                    # formats every .stn file under the current directory
stone fmt examples/basics.stn
stone fmt --check src

stone update [--check] [--version TAG]

Replaces the installed binary with a newer GitHub release, after verifying its checksum. With --check, it only reports whether a newer release exists, and --version installs a specific release, such as v0.2.0. Release binaries include this command. A stone built with cargo explains how to upgrade instead, unless it was built with --features self-update.

stone uninstall [--yes]

Deletes the running stone binary. It asks remove PATH? [y/N] first, and --yes (or -y) skips the question. Without a terminal on standard input it needs --yes. A binary in $CARGO_HOME/bin (by default ~/.cargo/bin) was put there by cargo install, so stone leaves it and tells you to run cargo uninstall stone. Windows cannot delete a program while it runs, so there stone renames itself to stone.exe.old at once, and a hidden cmd deletes that file once stone has exited.

Other options

  • stone --version prints the version.

  • stone --help and stone COMMAND --help describe the commands and options.