igl
One executable with six subcommands, on the model of phreeqc. It
lexes, validates, lowers, formats, explains and executes.
usage: igl <command> [options] <file>... --version print the version and exit --help print this text, or a command's own commands: check <file>... report diagnostics parse <file> print the syntax tree build <file> lower to the intermediate representation run <model> execute a lowered model fmt <file>... rewrite in canonical form, or verify explain <code> describe a diagnostic code
igl <command> --help lists the options that command accepts.
check
Parses, resolves and validates. Reports every diagnostic with its span, and
nothing else. Accepts --profile core|identification|extended;
Core is always accepted whatever is declared.
build
Lowers a validated model to model.iglir.json, attaching
provenance: the source path, its digest, and every database with the path it
resolved to and its digest. -o writes elsewhere.
run
Executes a lowered model and writes results.json. This is the step
a third-party engine replaces, and the conformance suite drives it through the
IGL_ENGINE variable for exactly that reason.
fmt
Rewrites in canonical form. --check reports a difference instead
of writing one, which is what a repository hook wants. The formatter is line
based rather than a reprint from the tree: a tree reprint drops comments, and
comments are the one thing an author most wants kept.
explain
Prints what a diagnostic code means, from the same registry that generates the diagnostics page.
Exit codes
| Code | Meaning |
|---|---|
| 0 | No errors. |
| 1 | The source has errors, or fmt --check found a difference. |
| 2 | Bad invocation, or a file could not be read. |
| 3 | This program has a defect and produced nothing trustworthy. |
Three is separate from two because a caller can fix its own invocation and cannot fix the tool's, so only one of the two is worth reporting upstream.
Environment
| Variable | Effect |
|---|---|
| IGL_DATABASES | Directory searched for a database named without a path. |
| IGL_PHREEQC | Path to a PHREEQC executable, when it is not on the PATH. |
| IGL_PHREEQC_DATABASE | Default thermodynamic database for PHREEQC backends. |
| IGL_ENGINE | Engine the conformance suite measures. Unset means the suite reports itself unmeasured rather than passing. |