Skip to content

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 Gale on Linux x86_64 or macOS 13 or newer on Apple Silicon:

Terminal window
curl -fsSL https://gale-lang.org/install.sh | bash

The 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:

Terminal window
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --version 0.1.0

Run 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:

Terminal window
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --uninstall

For 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.

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_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.

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,🌀}"]
]

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.

Rerun the installer and select proving tools, or request them explicitly:

Terminal window
curl -fsSL https://gale-lang.org/install.sh | bash -s -- --with-prover

The 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:

Terminal window
curl -fsSL https://gale-lang.org/install.sh | bash -s -- \
--yes --with-runtime --with-prover --no-modify-path

Use --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.

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.

Terminal window
mix gale.check
mix gale.verify --verbose
mix gale.verify --jobs 4 --json

One 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.

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.