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.stnfile, inside a project or not. A program of one file needs no project.Given a directory, as in
stone run app, they use itsmain.stn.stone checktakes a library’slib.stntoo.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.tomlor amain.stn. Sostone runworks 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 suggestsstone 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 |
|
arm64 Linux |
|
arm64 macOS |
|
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.stnbecomesbasics(basics.exefor Windows). Amain.stnis named after its package instead, thenameitsstone.tomlgives, so a projectmy-appthatstone initmade buildsmy-app/build/my_app. Without astone.tomlnaming one, amain.stnis named after its directory, as a program of several files usually is, sogeometry/main.stnbecomesgeometry/build/geometry.An executable for the machine stone runs on goes straight into
build/, and one for any other target intobuild/TARGET/, named as--targetnames 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 OUTPUTwrites the executable to exactlyOUTPUTinstead, with the assembly beside it with a.sextension, so it needs exactly one file and one target. A Windows executable is written toOUTPUTas given, so name itsomething.exeto 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:
pubdefinitions and the methods of apub struct, which other modules may use.The functions of a trait and of an
impl Trait for Tblock, 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 --versionprints the version.stone --helpandstone COMMAND --helpdescribe the commands and options.