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" }