Toolchain
Gale compiles typed source to readable Elixir. You need the compiler when building an application; deployed BEAM code does not invoke it. Start with Quick Start to run a first module.
Install or update
Section titled “Install or update”Install Gale on Linux x86_64 or macOS 13 or newer on Apple Silicon:
curl -fsSL https://gale-lang.org/install.sh | bashThe installer selects the Linux x86_64 or macOS ARM64 binary automatically.
The Linux release is a static musl binary. Windows, Intel macOS, and Linux ARM64
are not covered by these downloads. Release assets are served from
downloads.gale-lang.org.
By default, the installer resolves latest/PLATFORM to a semantic Gale release and installs
gale in ~/.local/bin. Running it again updates the compiler. SHA-256 checks
and a startup check finish before the installed executable is replaced.
The compiler installs without sudo. Optional runtime and proving setup may
ask to install system prerequisites. PATH setup adds a marked block to your
Bash or Zsh profile after confirmation.
To pin a release, replace 0.1.0 with its published semantic version:
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --version 0.1.0Run the installer with another --version to switch the active compiler. Each
release is downloaded from its immutable releases/VERSION/ path in R2, while
only one gale executable is active in the selected install directory. Remove
the compiler from the selected install directory with:
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --uninstallFor a non-default install directory, pass the same --install-dir to uninstall.
Uninstall removes only the PATH blocks it added and preserves edited blocks
and unrelated profile content. Modified compiler or adapter files are left
intact, with an error explaining why cleanup stopped.
Choose another destination with --install-dir /path/to/bin. For a private
mirror, use --base-url https://your-download-host or GALE_DOWNLOAD_BASE_URL.
GALE_INSTALL_DIR also sets the destination. The command-line options take
precedence. The installer source documents all options.
Add the destination to PATH, then run gale version. The version command also
reports the required solver versions. A release version matches the compiler
and Gale Mix package version; the internal CI build number is recorded only in
the release manifest.
Everyday commands
Section titled “Everyday commands”| Command | Purpose |
|---|---|
gale check |
Check source and contract types without generating files |
gale compile |
Check and emit .g.ex / .g.exs sidecars |
gale verify |
Prove selected source contracts with the proof toolchain |
gale format [--check-formatted] [--line-length N] |
Format Gale source |
gale clean |
Remove compiler-owned generated files |
gale guide |
Read the guide embedded in this compiler |
gale version |
Show compiler and required solver versions |
gale lsp |
Start the language server for an editor |
Use gale help <command> for command-specific options, such as gale help check
or gale help format. Every command also accepts --help without running it.
Sources can use .gale or .🌀; choose one extension for a module. Edit source files, never their generated sidecars.
Mix projects
Section titled “Mix projects”mix_gale runs Gale before Elixir compilation and supplies resolved dependency
roots and application names. Public Mix packages are being prepared; existing
preview projects already carry their integration settings. Keep the compiler
and Gale libraries on the same release revision, and commit mix.lock.
The Mix plugin never downloads the compiler or solvers during a build.
gale new creates a Mix project with complete copies of mix_gale and
gale_std under vendor/, matched to the compiler that created it.
The repository is private for now, so releases bundle these sources.
Mix uses local path dependencies. Keep vendor/ in version control.
Follow Quick Start to create a project.
The plugin looks for gale: [compiler_path: ...] first, then gale on PATH.
Run mix gale.path to see the selected compiler. To select an explicit binary
in mix.exs:
gale: [compiler_path: "/absolute/path/to/gale"]To allow an environment override with PATH as the fallback:
gale: [compiler_path: System.get_env("GALE_COMPILER_PATH")]mix compile, mix gale.check and mix gale.verify use the same project
configuration. Prefer these commands inside a Mix project: a direct CLI
invocation does not evaluate mix.exs or discover its dependencies.
Library module names must equal the Mix application name or begin with it
and a dot: shop.orders belongs to shop. Test module names end in _test.
Tests and proofs serve different purposes; run both.
Editors and formatting
Section titled “Editors and formatting”gale format wraps long expressions toward 98 columns. Set another positive target
with gale format --line-length 80; --check-formatted reports files needing
formatting without changing them. Existing line boundaries, comments and literal
bytes are preserved. Strings, comments and identifiers can exceed the target when they
cannot be split safely.
Pipe source through gale format - to read stdin and write the formatted result to
stdout. gale format --check-formatted - produces no source output and exits with
status 1 when formatting is needed. Stdin must be the only input; invalid options
exit with status 2. Malformed input is rejected without writing its source.
Gale’s VS Code integration uses the compiler’s language server. Keep
gale on the editor’s PATH. gale.path can select an explicit
compiler; trusted Mix workspaces can resolve it through mix gale.path.
Restart the language server after changing dependencies or package names.
Highlighting combines the syntax grammar with semantic colors from compiler
observations. Hover, completion details, and signature help render Markdown
documentation and show declared function contracts (requires, ensures, and
decreases), including shared signatures with multiple clauses. Hover also
retains pure and receives annotations. Displaying a contract does not prove
it; use mix gale.verify to check its proof obligations.
Public editor distribution is being prepared alongside the first release.
Include Gale files in .formatter.exs:
[ plugins: [MixGale.Formatter], inputs: ["{mix,.formatter}.exs", "{lib,test}/**/*.{ex,exs,gale,🌀}"]]Runtime boundary checks
Section titled “Runtime boundary checks”gale: [runtime_typechecks: Mix.env() == :test] enables generated boundary
checks in tests. They inspect supported runtime shapes and evaluate executable
requires, ensures, assert, ghost statements and opaque invariants. False
conditions raise Gale.Check.ContractError with the Gale source location; type
failures raise Gale.Check.TypeError. Extern preconditions run before the native
call and postconditions check the actual adapted result. Callback invocation and
source behaviour implementation contracts are checked too. These checks validate
function and callback interfaces using evaluators emitted in the checked caller,
so their declaring dependencies can be compiled without checks. They validate
executed cases; they do not replace gale verify, validate mailbox payloads, or
recover erased generic or nominal information. Finite literal unions, finite
tuples and non-generic fieldless ADTs can be enumerated in quantifiers (up to
1024 values per domain). Collection membership/count formulas use finite lists,
tuple projections, map keys or entries and MapSet contents when the formula is
known to hold outside that support. Bounded Integer quantifiers enumerate the
complete concrete interval.
String prefix/suffix/substring formulas use exact UTF-8 byte matching.
Quantified postconditions describing returned functions attach checks to their
later invocations, including functions in record fields. Actual arguments
instantiate the quantified parameters, and the actual result is reused without
calling the function twice. Such returned functions are wrapped, which can
change their native function identity. This checks executed calls, not every
possible future input. Unbounded quantifiers, including generic ones, use the
current call’s concrete values, including collection elements and actual callback inputs and outputs.
These bindings are local to the call; gale verify establishes universal claims.
Loop-invariant formulas can use actual callback transitions as an induction
certificate without invoking hypothetical predicates.
Quantified requirements on callback arguments check their actual invocations and
retain those checks when returned. Existential list formulas can evaluate an
emitted predicate using an accumulator witness from actual callback results.
Callback arguments crossing native or source dependency
boundaries can also be wrapped to check their actual inputs and outputs and record
results. Postconditions reuse those results without repeating the corresponding
callback calls; these wrappers can change native function identity.
Other unbounded quantification and abstract callback-contract
observations requiring an inferred closure model cannot be evaluated generally.
Runtime proof checks are best effort: unsupported or inconclusive checks are
skipped without blocking compilation or raising at runtime. Independent supported
clauses and conjuncts still run; established violations still raise. Skipped
checks do not establish truth. Ordinary conditions use the actual supplied
arguments and returned values. Callback outcome
observations reuse the current execution’s recorded results for those arguments.
Declared callable-interface observations evaluate their contracts without
invoking the callback; pure outcome observations still require an executable
outcome model. Opaque
invariants are checked when the owner supplies a runtime evaluator. If the owner
was compiled without runtime checks, callers still check the representation and
skip the unavailable invariant. Explicit decreases
measures check well-founded lexicographic descent on recursive re-entry.
Validate external input before constructing application values; see decoding.
Proof toolchain
Section titled “Proof toolchain”Rerun the installer and select proving tools, or request them explicitly:
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --with-proverThe installer checks for a working adapter and the required Why3/Z3 versions. If needed, it installs a private opam environment and builds the matching adapter from the selected release’s bundled source. This can take several minutes.
The release metadata pins the tool versions. Managed runtime and proof files
live in .gale-toolchain beneath the chosen install directory, with an
installation receipt and shell activation file. Pre-existing tools are reused;
shared prerequisites installed through apt or Homebrew are retained on uninstall.
On macOS, proof setup uses Homebrew and offers to install it if needed.
For unattended installation, select the components explicitly:
curl -fsSL https://gale-lang.org/install.sh | bash -s -- \ --yes --with-runtime --with-prover --no-modify-pathUse --without-runtime or --without-prover to skip a component.
--modify-path enables shell setup; --no-modify-path disables it.
Without a terminal or explicit setup flags, the script installs only the compiler.
--yes accepts the default runtime and PATH setup, with proving still opt-in.
Compilation, formatting, and runtime tests do not need proof tools. The Mix plugin never installs them during a build.
Run gale version to see the supported pair. gale verify rejects mismatched
tools; mix gale.verify uses the same verifier. A setup failure, timeout or
unsupported feature is never a successful proof. Read the
verification reference for the precise scope and limits.
Verification
Section titled “Verification”mix gale.check typechecks source and contracts without solvers or sidecars.
A well-typed false contract can pass checking. Configure a nonempty list of
proof commitments before running mix gale.verify:
gale: [ compiler_path: System.get_env("GALE_COMPILER_PATH"), proofs: [ "my_app.accounts/increment", {"my_app.accounts/reserve:2", goal: 30, wall: 90} ]]Replace the subjects with canonical names from your application. A function
entry module/name selects every arity; module/name:arity selects one.
Predicates and lemmas use module/predicate:name and module/lemma:name.
Each listed subject must match, and all its required implementation/dependency
obligations must succeed. Tests are typechecked; include their subjects in the
list when they should also be proved.
mix gale.checkmix gale.verify --verbosemix gale.verify --jobs 4 --jsonOne verifier process handles the whole list. Defaults are 5 seconds per goal,
120 seconds of shared wall time including preparation, and one worker. An entry’s
goal: overrides its solver limit; wall: gives it a separate proving budget
starting when the unit begins, without spending the shared wall. Raising a goal
limit does not raise its wall limit. gale: [options: ["--jobs", "4"]] passes
extra arguments to the process. Command-line flags override matching options;
entry-specific limits still take precedence for that subject.
mix gale.verify selects scope through proofs, and rejects --module and
--subject command-line flags. Standalone gale verify accepts both selectors:
--module selects module roots and --subject selects named subjects. Without
selectors, the standalone CLI selects application library modules. Direct CLI
calls need explicit resolved project/dependency inputs; they do not load Mix.
Use mix help gale.verify and gale help verify for accepted flags. --verbose
reports progress; --json writes the structured report to stdout with progress
on stderr. Successful units are reused from .gale/proofs; keep .gale/ out of
source control. --cache-dir DIR overrides the location. Setup errors, empty
runs, unsupported lowering, timeouts and unproved obligations fail the task.
Proof guarantees and trust boundaries are described in the
verification reference.
Clean generated output
Section titled “Clean generated output”gale clean or mix gale.clean removes sidecars identified by the generated
header and leaves handwritten Elixir intact. Cleaning works even when the
source no longer typechecks. Run gale compile or mix compile to regenerate
output from current sources.