polar

Command Line

Everything Polar does goes through one command, polar. This page lists every subcommand and flag.

Usage: polar [OPTIONS] <COMMAND>

Commands:
  build
  check
  run
  fmt
  start
  init

Inside a project, path arguments are optional: commands use the project you're in.

polar run

polar run [OPTIONS] [FILE] [-- <ARGS>...]

Compiles a file or project and calls its exported main. Arguments after -- reach the program as Process.args().

Flag Does
--host <HOST> Picks which host to run for, when there are several
--watch Rebuilds and restarts the program whenever a source file, polar.toml or a path dependency changes
--target <TARGET> js (default) or native. Native builds a one-file executable and runs it. See Native executables
--debounce <MS> With --watch, how long to wait after a change before rebuilding (default 100)

If the project sets a launcher in [run], polar run without --host builds every host and hands the build to the launcher instead.

With --watch, a build error is printed and the running program keeps running until the next good build. The restarted program gets the same arguments and environment.

polar check

polar check [OPTIONS] [PATHS]...

Type-checks and reports errors without writing anything. It's the fastest way to see whether code compiles.

Flag Does
--watch Checks again on every change
--out <OUT> A folder to skip when looking for source files and watching for changes, like a build folder

polar build

polar build [OPTIONS] [PATHS]...

Writes .js, .js.map and .d.ts files, plus the runtime and a start.mjs entry point. With several hosts, it writes one folder per host: dist/Browser/, dist/Node/.

Flag Does
--out <OUT> Where to write. Defaults to the project's out, or dist
--watch Rebuilds on every change
--host <HOST> Builds only one host, into dist/
--target <TARGET> js (default) or native
--triple <TRIPLE> With --target native, the platform to build for, such as x86_64-unknown-linux-gnu
-o, --output <FILE> With --target native, the file to write. Defaults to dist/<name>
--emit <STAGE> Prints one compiler stage for a single file instead of building

--emit takes one of these stages:

Stage Prints
tokens The tokens the lexer produced
ast The parsed syntax tree
core The simplified core language
types The inferred type of every declaration
hosts Where each function can run. See Hosts
dictionaries How trait implementations are passed around
js The generated JavaScript

Tip: --emit=types is a quick way to see what Polar inferred for a function you didn't annotate.

Native executables

$ polar build --target native
dist/app
$ ./dist/app

--target native writes one executable that runs without Node. It is a copy of polar-rt, a Rust evaluator that ships next to polar, with your compiled program attached to the end. The program is interpreted, so it is slower than Node's JIT and plenty fast for command-line tools.

The build takes the Native host, which has Time, Url, Regex, Crypto, Fs and Process. A function that needs something else is reported as POLAR0824, with a hint on where to add the rs implementation. See Hosts. Cross-compiling is a file copy: --triple looks for polar-rt-<TRIPLE> beside polar, or in POLAR_RT_DIR. --watch and --emit don't work with --target native.

polar fmt

polar fmt [OPTIONS] [PATHS]...

Formats files in place in the standard layout.

Flag Does
--check Only reports files that would change, and fails if there are any
--idempotent With --check, formats twice and fails if the second pass changes anything
--expect <FILE> Formats the one input in memory and compares it with FILE, printing a line diff and exiting 1 if they differ. Never writes

polar fmt skips x.px when x.expected.px sits next to it, skips *.expected.px files, and skips paths listed under [fmt] exclude in polar.toml. A file named on the command line is always formatted.

polar test

polar test [OPTIONS] [PATH] [-- <NODE_ARGS>...]

Builds the project to a temporary folder and runs its tests on Node. A test file is any *_test.px under the project's src, such as money_test.px next to money.px. A test is an exported function whose name starts with test_ and that takes no parameters. The compiler checks both: a test with parameters is an error, and an exported function in a test file without the prefix is a warning, so a misspelt tset_x doesn't silently go unrun.

Flag Does
--filter <TEXT> Runs only the tests whose name contains the text, such as cart_test::test_add
--timeout <MS> How long one test may run (default 5000)
--bless Rewrites expect-error annotations and snapshots from what actually happened. POLAR_UPDATE=1 does the same
--format <FORMAT> text (default) or json: one object per test, then a final result object
-p, --project <NAME> In a workspace, runs only the members with this project name. Repeatable
-j, --jobs <N> In a workspace, runs this many members at once (default 1)

The tests run one after another, in order, and a failing test never stops the run. Each one ends as ok, FAILED (an Std.Assert check failed), ERROR (anything else was thrown, such as an uncaught typed error or an exception from JavaScript) or TIMEOUT. A failure points at the line in the .px file, and what the test printed is shown only when it didn't pass.

running 3 tests
test cart_test::test_add ... ok
test cart_test::test_empty ... FAILED
test slow_test::test_wait ... TIMEOUT

failures:

---- cart_test::test_empty ----
failed at src/cart_test.px:15:5:
expected 0, got 1

failures:
    cart_test::test_empty
    slow_test::test_wait

test result: FAILED. 1 passed; 2 failed; 0 filtered out; finished in 5.01s

The exit code is 0 if every test passed and 1 otherwise, or if the project doesn't build. A project with no test files prints no tests found and exits 0. Arguments after -- go to Node. See Std.Test for the runner itself.

Tests that expect an error

A file that must not compile is a test too. Put an expect-error comment above the line that should fail:

functions
  total(xs: List<Int>) -> Int {
    // expect-error: POLAR0501 "mismatched types"
    List.length(xs) + "one"
  }

The file is one test, named by its path (such as routes_errors::unknown_action). It passes when every annotation matches an error with that code on the next line of code, and fails if the file compiles, a code or line differs, or an error has no annotation. The quoted text is optional and only has to be part of the message. Files with annotations are left out of polar build, polar check and --watch.

Around, capture and snapshots

A test file may define around_each(run: function() -> {} / {| e}) -> {} / {| e}. Every test in that file then runs as around_each(test), which is where set-up and tear-down go. A test's stderr is merged into its stdout, so a test that passes prints nothing. For mocking an effect, capturing Log, snapshots and an HTTP client, see Std.Test.

Workspaces

A repository with many projects can name them all in a root polar.toml that has no project of its own:

[workspace]
members = ["tests/*", "examples/blog"]
exclude = ["tests/fixtures"]

A member is a directory with a polar.toml, written out or as dir/* for every subdirectory that has one. Run polar check, polar build, polar fmt or polar test at the root and each one acts on every member. For polar test, a failing member doesn't stop the others. Each member's output comes under a project <dir> line, and the report ends with one total:

workspace result: ok. 3 projects; 41 passed; 0 failed; 0 filtered out; finished in 4.2s

polar repl

polar repl [OPTIONS] [PATH]

Loads a project and evaluates one expression or binding at a time on Node. Every project module is in scope, along with the modules your files import and a few pure standard ones (List, Option, Result, Map, Json, Ref, Table, Math).

$ polar repl
polar> let post = Greet.post()
post: { id: Int, title: String } as Post = { id: 1, title: "Hi" }
polar> post.title
String = "Hi"
polar> :type Greet.hello
function(String) -> String

An expression prints its type and its value, using Show, or the derived Json when there is no Show, or <no Show for T>. A let prints the name, type and value, stays in scope for later lines, and a later let of the same name shadows it. A line with a parse or type error prints the diagnostic and keeps the session going. Bindings are replayed ahead of each new line, so an effectful let runs again every time.

Effects run under the binds the project declares. An effect with no bind is reported as a diagnostic on the line.

Flag or command Does
--setup <MODULE.FUNCTION> Runs a () -> {} function once before the first prompt, such as one that connects a database. If it fails, the exit code is 1 and the prompt never starts
-e, --eval <EXPRESSION> Evaluates the expression, prints, and exits
:type <expr> Prints the type without evaluating
:reload Recompiles the project and keeps the bindings that still type check
:help, :quit Show the commands, or leave. Ctrl-D leaves too

Piped input works the same as typing: echo '1+1' | polar repl prints Int = 2. When input is piped or given with -e, the exit code is 1 if any line errored. There is no line editing or multi-line input; wrap the command in rlwrap for history.

polar start

polar start [OPTIONS] [PATH] [-- <ARGS>...]

Runs an existing build without compiling. It's the same as node dist/start.mjs.

Flag Does
--host <HOST> Picks which host's build to run

polar init

polar init [OPTIONS] [DIR]

Starts a project: writes polar.toml, src/main.px and a .gitignore. With no DIR it uses the current folder; otherwise it creates DIR (and any parents). It never overwrites: if polar.toml exists it stops, and existing src/main.px or .gitignore files are kept.

Flag Does
--name <NAME> Project name. Defaults to the folder's name, lowercased, with - and spaces turned into _
--zone <KEYWORD> Adds a zone plugin stub and the .polar/ folder. Repeat it for several zones

Dependency commands

polar add <ADDRESS>[@<VERSION>]
polar remove <NAME>
polar fetch [--verify]
polar update [NAME]

Manage git dependencies. They edit polar.toml and polar.lock in the current folder. See Git dependencies.

Command Does
add Adds a dependency. With no @ it picks the newest tag; @v1.4.1 picks a tag, @main a branch and @<sha> a commit
remove Removes a dependency and drops what only it needed
fetch Resolves every dependency, downloads it and writes polar.lock. --verify re-checks the cached files against their checksums
update Moves one dependency, or all of them, to the newest tag (branches to their newest commit)

Global flags

Flag Does
--color, --no-color Forces colored error output on or off
--offline Never touches the network: fails if a git dependency isn't cached. POLAR_OFFLINE=1 does the same
-V, --version Prints the version
-h, --help Prints help, for polar or any subcommand

polar.toml

The project file, for reference. Every key is described in Your First Project and Modules and Packages.

[project]                       # or [package] for a library
name = "app"
src = "src"
out = "dist"
main = "src/main.px"
hosts = ["Browser", "Node"]

[fmt]
exclude = ["tests/*/fmt"]

[dependencies]
shapes = { path = "../shapes" }
ticket = { git = "github.com/owner/ticket", version = "v0.1.0" }

[run]
launcher = "simple_framework"
options = { port = 3000 }

# a root that only lists projects (no [project] or [package])
[workspace]
members = ["tests/*", "examples/blog"]
exclude = ["tests/fixtures"]

# packages only
[package]
name = "simple_framework"
module = "Framework"
polar = "0.4.0"

[launcher]
script = "launcher/serve.mjs"

[plugin]
zones = ["schema"]
dependencies = { regex = "1" }