Compiling
jaic compiles, checks and runs Jai programs. jacket build, check and run pass the flags of jaic through untouched (single-dash, as in jacket build -o -exe app main.jai) and add the project: with no .jai file named they build [project] entry from the nearest jacket.toml (else build.jai, first.jai, main.jai, src/main.jai or module.jai), and [experimental] settings become jaic flags unless you pass them. The jaic command line says how the flags fit together.
Commands
| Command | Meaning |
jacket build | Compile a program: jaic <args>, flags untouched |
jacket check | Type-check without writing anything: jaic -check <args> |
jacket run | Build, then run the program; arguments after -- go to it (-interp runs it in jaic) |
jacket clean | Remove the executable jacket build writes |
jacket jaic | Run jaic with exactly these arguments |
jaic
jaic: compile, check and run Jai programs
jaic [options] file.jai [options] [+Plugin [plugin options...]]... [- metaprogram args...] [-- program args...]
By default jaic builds a native executable. Options may come before or after the file.
Modes
| Option | Meaning |
-check | compile the program without running or writing anything |
-interp | run main in the interpreter (arguments after -- go to the program) |
-deps | like -check, then print every source file the compile read, one per line |
Program
| Option | Meaning |
-add "code" | add the code to the target program (repeatable) |
-run "code" | run the code at compile time, as a #run (repeatable) |
-import_dir <dir> | also look for modules in <dir> (repeatable; short form -I) |
-os <os> | target OS: linux, windows, macos or wasm |
-cpu <cpu> | target CPU: x64 or arm64 |
-target <triple> | build for an LLVM target triple (overrides -os and -cpu) |
-no_dce | type-check unreferenced module code too |
-no_check | accepted and ignored: jaic does not run the Check plugin unless asked |
-no_check_bindings | set CHECK_BINDINGS=false on a +Check plugin, if there is one |
Output (building only)
| Option | Meaning |
-j, --jobs <n> | run n compiles (or tests) at once (default: one per CPU) |
-exe <name> | the executable's name; it may include a directory and extension (-exe build/app.exe). A bare name goes in the current directory |
-output_path <dir> | the directory the executable is written to |
-o, -optimized | optimized build (LLVM O2) without stack traces or runtime checks |
-od, -optimized_debug | lightly optimized build (LLVM O1) that keeps stack traces and checks |
-very_debug | unoptimized build with every runtime check on |
-O0, -O1, -O2, -O3 | pick the LLVM optimization level directly |
-no_inline | do not inline procedures |
-no_split | generate code as one module instead of several |
-backtrace_on_crash | install the crash handler (a metaprogram's setting wins; -no_backtrace_on_crash overrides) |
-no_backtrace_on_crash | leave the crash handler out of the program |
-emit_ir <file.ll> | also write the LLVM IR |
-no_debug_info | leave out native debug information |
-sanitize <list> | address, undefined and/or fuzzer, comma-separated |
-coverage | record line and function coverage (docs/tools/coverage.md) |
-no_workspace_output | (-interp only) do not write what a metaprogram's workspaces ask for |
-codegen_units <n> | generate code as exactly <n> modules (1 is -no_split; only a build uses it) |
-threads <n> | threads in the pool that code generation and other parallel work share (default: one per core) |
-parse_threads <n> | threads that parse files ahead of the checker (0 parses serially) |
-serial_parse | parse every file on the checking thread |
Plugins
| Option | Meaning |
+Name | run the metaprogram plugin module Name. Every argument after it, up to the next +Name, - or --, is that plugin's own option. Module parameters go in the name: '+Check(CHECK_BINDINGS=false)' (quote it in a shell). With -interp the program they compile is run. |
- | the rest is for the metaprogram (compiler_get_command_line) |
-- | the rest is for the program (-interp only) |
Diagnostics and output
| Option | Meaning |
--color <when> | colour in diagnostics: auto, always or never |
-A <code> | allow a warning: print nothing (warnings for all, leniencies for the forms the official compiler rejects; jacket explain lists the codes) |
-W <code> | warn about a code (the default) |
-D <code> | deny a warning: print it as an error and fail (-D warnings for all) |
-no_color | no colour in diagnostics |
-msvc_format | one path(line,col): error: message line per diagnostic |
-quiet | print nothing but errors (no build status either) |
-verbose | say what is being done |
-timings | print the wall time of each phase on stderr |
-h, -help, --help | print this help |
-print_stdlib | print the standard library folder jaic uses and exit |
-doc_comments <dir> | print the doc comments of the library in <dir> as records, for jacket test; -import_dir folders are searched for the modules it imports |
-doc_gaps <dir> | print which public declarations of the library in <dir> have docs and an example; -import_dir folders are searched for the modules it imports |
-doc_model <dir> | print the documentation of the library in <dir> (items, signatures, docs) as JSON, with what its public top-level #inserts declare (compiled once with default module parameters), for jacket doc |
-procedures <dirs> | print every procedure with a body below the folders <dirs> (a path list) as records, for jacket test --coverage; -os and -cpu pick the #if branches |
-V, -version, --version | print the version |
-profile | count what the interpreter runs per procedure and print the busiest |
-profile_runs | print the compile-time runs (#run, constants, metaprograms) by the work they did |
-run_budget <steps> | steps (loop iterations and calls) one compile-time run may execute before it fails (default 1000000000; 0: no limit) |
Environment
| Variable | Meaning |
JAIC_MEMORY_LIMIT=<bytes|nK|nM|nG> | stop with exit status 120 once that much is allocated |
JAIC_DIAGNOSTICS=plain|ascii|unicode | diagnostic layout (default: by terminal) |
NO_COLOR, FORCE_COLOR, CLICOLOR_FORCE | turn colour off or on |
exit status: 0 success, 1 the program failed to compile, an input file cannot be read or a runtime error stopped it (-interp otherwise exits with the program's own status), 2 a command-line mistake, 3 a build found no main to make an executable from, 120 the memory limit, 121 native code crashed under the interpreter, 101 an internal compiler error