Command line

Every osl command, its usage line and its flags, with an example of each, plus the environment variables the compiler reads.

osl is one program that runs, builds, tests, formats and inspects OSL code. This page lists every command and flag in OSL 9.3.0. Run osl with no arguments (or osl help) for the short summary, and osl version for the installed version.

osl <command> [options]

Most commands have no --help: given the wrong arguments they print their usage line, and that is the line shown under each command below. Only bench and lsp accept -h.

Exit codes#

osl run is different: it returns the exit status of the program it ran. When the program is killed by a signal, run returns 128 plus the signal number, as a shell does.

Options that work everywhere#

Without --all-warnings, the build commands print at most 20 warnings and count the rest. See Diagnostics for what each warning means.

run#

Compiles a program to a temporary executable, runs it, and deletes it. The program's working directory is the folder of the source file.

osl run <file.osl> [--no-cache] [-v|--verbose] [-- program args]

test blocks are left out of the program.

osl run hello.osl
osl run server.osl -- --port 8080

compile#

Builds a native executable you can copy to another machine of the same operating system and architecture. It needs no OSL installed to run.

osl compile <file.osl> [-o <output>] [--no-cache] [--no-write] [--optimise]
            [-v|--verbose] [-- program args]

osl compile todo.osl -o todo
osl compile todo.osl --no-write
osl compile server.osl --optimise -- --self-test

test#

Finds and runs the tests under the paths you give (the current folder when you give none). It takes no flags. Testing covers the test blocks, the output and the exit codes.

osl test [path ...]

osl test
osl test src/
osl test src/pricing.osl

opal#

Opal is the package manager. osl opal <command> and the opal program run the same code. Opal lists every subcommand.

osl opal <command> [options]

osl opal init
osl opal add someone/some-package

fmt#

Rewrites source files in the canonical style: two-space indentation, tight call parentheses, a blank line between declarations. It leaves a file untouched when it does not parse, and never changes what a program means. A directory is searched recursively. It prints the path of every file it checked.

osl fmt <file-or-directory> [...]

osl fmt src/
osl fmt main.osl lib/

fix#

Applies the fixes the editor offers as quick fixes, and rewrites old syntax the compiler no longer accepts (old type declarations, reserved names used as variables, old lambdas and string escapes, and the functions that became methods, such as sqrt(x) and keys(o)). It repeats until nothing more changes, up to 8 rounds, and prints the files it changed.

osl fix <file-or-directory> [...] [-v|--verbose]

osl fix .
osl fix main.osl -v

transpile#

Prints the Go program that a file compiles to. Useful to see what the compiler does, or to report a bug.

osl transpile <file.osl> [--no-cache] [--explain-ownership] [-v|--verbose] [-o <file>]

Only the functions and methods a program reaches are included, so the output stays small.

osl transpile main.osl
osl transpile main.osl -o out/main.go

asm#

Prints the Go assembly the program compiles to. Each instruction names the OSL line it came from, so you can see how a statement was lowered. The output is large: write it to a file.

osl asm <file.osl> [-o <file>] [--no-cache] [-v|--verbose]

osl asm hot.osl -o hot.s

ast#

Prints the parsed syntax tree of one file as JSON. It parses only: it does not type check.

osl ast <file.osl>

osl ast main.osl > main.ast.json

lsp#

Starts the language server on standard input and output, for editors. With check, it prints a file's diagnostics, and those of every file it imports, and exits with status 1 if any is an error. Editor support has the details.

osl lsp [check <file> [-v|--verbose]]

osl lsp check src/main.osl

bench#

Runs a program repeatedly and reports where it spends time and memory. The program's own log output is discarded while it runs.

osl bench <file.osl> [--time 1s] [--runs N] [--top N] [--profile cpu.pprof] [-- program args]

The report has four parts:

• CPU self time splits samples between generated OSL and runtime code, the Go runtime, reflection, and system calls.
• Hot generated functions lists functions by cumulative cost.
• Hot OSL source lines lists your own lines by self time.
• Hot allocations comes from one extra run with allocation profiling on, and lists allocation sites by bytes and object count.

osl bench sort.osl --time 3s --top 10
osl bench fetch.osl --runs 1 -- https://example.com

package#

Prints the source of a standard package, with the header that lists what it needs. With no name, it lists the packages. For a family such as encodings, it lists the members.

osl package [name]

osl package
osl package fs
osl package std:json

cache#

The compiler stores compiled programs, module snapshots and generated workspaces so the second build of anything is fast. The cache lives in the user cache folder, under osl.

osl cache status
osl cache clean

Installation commands#

osl setup
osl update [-v|--verbose]
osl uninstall
osl version

Environment variables#