# Changelog

## v0.2.1 - 2026-11-10

* Docs only. The README's guide links open the HexDocs pages again (on
  hex.pm they opened the raw Markdown), `Precompiled.Host.run/1`
  documents its own `report()` type, and the docs build without
  warnings.
* `mix hex.publish` runs in the docs env, where ex_doc lives.

## v0.2.0 - 2026-11-10

* Renamed to `precompiled` before the first Hex release: the app and
  package `:precompiled`, modules `Precompiled.*` (the host API, `run/1`
  and the `Mix.install/2` wrapper `install/2`, is now `Precompiled.Host`;
  `Precompiled` itself is the device API), config `config :precompiled`,
  environment variables `PRECOMPILED_*`, the default cache dir
  `:filename.basedir(:user_cache, "precompiled")`, the provenance file
  `.mix/precompiled.json` and the archive `precompiled-<vsn>.ez`. The
  Igniter installer is `mix igniter.install precompiled`
  (`mix precompiled.install`), and the `deps.loadpaths` step it adds is
  now `mix precompiled.deps`. A clean break: none of the interim
  `elixir_precompiled` names is read, and a cache under the old dir is
  simply not used. The repository keeps its name, `elixir_precompiled`.
* `Precompiled.install/1,2` installs signed precompiled builds into a
  running Nerves device from an IEx shell, with no Mix, Hex or compiler on
  the device: it selects the build for the device's system, OTP, Elixir,
  CPU and present apps (by name and exact version), verifies every byte,
  loads and starts it with its absent runtime dependencies, and rolls the
  whole call back on any failure. Nothing present is ever replaced.
  `Precompiled.list/1`, `Precompiled.uninstall/2` and `dry_run: true`
  (with `report:` for a bundle) come with it. See the "On a
  device" guide.
* On by default, with the official signed source
  (`https://compatibility.nerves-project.org/api/precompiled`) as the
  default source; it only acts when called. `config :precompiled,
  :device` sets `enabled: false` (no installs), `allow: [...]` (an allowlist),
  another `source`, `dir`, `max_bytes` and `cacerts_path`; `enabled` and
  `allow` cannot be overridden by a call.
* Installs are kept as a cache on `/data` across reboots, never loaded at
  boot; installing again loads from the cache after re-verifying every
  file. The cache is bounded by `max_bytes` with least recently used
  eviction, and `Precompiled.clean/0` empties it.
* `file://` sources: a bundle directory with the API's layout, read from
  local storage only, with no network and no network apps.
* Offline bundles: a bundle's `offline.json`, signed by the root's
  `offline` role, has no expiry and needs no clock; a device honours it
  only from a `file://` source, under a root with an `offline` role, and
  never below the highest offline sequence it has seen. A device adopts a
  newer root from a bundle when it chains. The shipped root has no
  `offline` role yet, so a bundle is valid for its batch's 24 hours.
* `mix precompiled.bundle PKG[@REQ]... --out DIR` writes a bundle on a
  host with network, planned from the device's facts (flags, or a dry
  run's `--device-report`), with every byte checked before it is written.
* `mix igniter.install precompiled --device` keeps the dependency
  at runtime so it ships in the firmware, and adds `castore` unless the
  project already depends on it.
* `:inets`, `:ssl` and `:public_key` are optional applications; `:crypto`
  stays required. A firmware without them installs from bundles only (an
  online call returns `{:error, {:missing_app, app}}`).
* `cacerts_path:` (an option of `Precompiled.install/2` and a `:device`
  config key) names a PEM CA bundle for a device install. Without one (and
  without `PRECOMPILED_CACERTS_PATH`/`HEX_CACERTS_PATH`),
  an empty or missing OS certificate store now falls back to the `castore`
  package's bundle when that is loaded. With no certificates at all the
  error now reads `no CA certificates` (before: `no CA certificate store on
  this system`), and an empty store is that error too, never a TLS attempt
  with no CAs.

* The host's check that an installed build is still intact is stricter
  about `priv`: a `priv` that is a copy rather than Mix's link to the
  dependency's sources (as on Windows, where links may be refused) no
  longer counts as intact, so such a build is installed once more.
* `enabled: false` disables `install/2` only: `list/1`, `uninstall/2`
  and `clean/1` keep working, so what is installed can still be removed.

## v0.1.0 - unreleased

* Any Mix project can use it: `mix precompiled.deps`, reached through a
  `deps.loadpaths` alias (`mix igniter.install precompiled` adds it),
  installs builds before Mix compiles dependencies in plain projects,
  umbrellas and Phoenix apps, and for Nerves with released nerves too,
  where only `pure_elixir` builds match: system (target) builds need the
  Nerves fork's `Nerves.build_plan/0` to name the system.
  `Precompiled.Host.run/1` for the nerves hook is unchanged. The Igniter
  installer sets the dependency `runtime: false`, `:source` in
  `config/config.exs` and the alias, prepended to an existing one; Igniter
  is an optional dependency, declared only on Elixir 1.18+.
* Never fails a build: any internal error is one warning and a source
  compile; no `HOME` or an unwritable cache moves the cache under `_build`.
* Warm runs make one conditional batch request (`If-None-Match`) and
  download nothing once the source answers `If-None-Match` with `304` (until
  then the batch itself is downloaded again; manifests and files still come
  from the cache); the root is checked at most once an hour; manifests are
  cached by SHA-256; files of a dependency download in parallel.
  `PRECOMPILED_OFFLINE=1` works from the cache; a run has a network
  deadline (`:deadline_seconds`, 300; root and batch 15 s). When the source
  cannot be reached, a cached batch that still passes every check is used;
  a refused response never falls back. A source that failed to connect is
  then not asked again in that run, so uncached manifests and files miss at once; a content
  origin that fails to connect is skipped for the run (the source still
  serves).
* Content origins: the signed batch (or `:content`) may name CDNs for files
  and manifests, with fallback to the source; every byte is still checked.
* An installed build is kept while the batch still offers its exact files,
  so a new portal run of the same inputs no longer recompiles the project.
* Install refuses colliding paths (duplicate, case or Unicode variants,
  `path collision: ...`), paths that are not plain relative paths inside
  the dependency's own build dir (`unsafe path or mode (...)`), `ebin/`
  entries other than beams, `<dep>.app` and `<dep>.appup`, such as another
  app's `.app` (`foreign path: ...`), and beams the `.app` does not list; linking happens before the install is renamed into place. A cache
  entry that is a symlink is never followed: that dependency compiles, and
  the line names the path to remove.
* Dependencies that read `Mix.target()` or environment variables at compile
  time are matched on them (README, rule 8).
* `nerves`' own dependencies are recognised from Mix's dependency data, so a
  git or path `nerves` keeps them out.
* `PRECOMPILED=0`, or no source configured, now removes installed
  builds (Mix compiles them in that run). Only the `_build` of the run's
  own env and target is touched: under Nerves a run on `host` removes the
  host installs, never a device target's.
* `mix precompiled.status` and `mix precompiled.clean [--cache]`; the cache
  is bounded (`:cache_max_mb`, 4096).
* A batch the source did not deliver is reported as
  `batch unavailable: <why>` (before: the bare reason); a delivered batch
  that fails a check is still reported by the check alone (`batch stale`,
  `batch signature invalid`, ...).
* Lower-case proxy variables, `NO_PROXY`, and a CA bundle
  (`PRECOMPILED_CACERTS_PATH` or `HEX_CACERTS_PATH`). The bundle
  replaces the OS store, as Hex's does: verification stays on and only its
  CAs are trusted.
* `PRECOMPILED_SOURCE` opts in without a config change; it wins over
  app config, an explicit `source:` option wins over it. An empty value
  counts as unset.
* `Precompiled.Host.install/2` on Elixir 1.17 and 1.18 installs into the
  dir `Mix.install/2` uses there (`elixir-<vsn>-erts-<vsn>`); before, its
  installs landed beside it and Mix compiled everything.
* CI runs Elixir 1.17 to 1.20.
* A batch issued more than 24 hours ago, more than 5 minutes in the
  future, valid for more than 30 days, or read against a local clock
  earlier than this library's build time, is refused; the run falls back
  to compiling, same as an expired or rolled-back batch.
* Every run, `Precompiled.Host.install/2` included, rechecks
  dependencies an earlier run installed (in a Mix project's `_build` or
  the `Mix.install/2` project) against the current batch: one the batch no longer names, or one newly listed in
  `:except`, is removed and compiled from source; one whose manifest
  changed is matched again. When
  no batch is available, installed builds are left as they are and one
  warning line says how many were kept, not rechecked (`report.json`
  still lists each as `fail`, `(installed build kept)`). Builds
  installed by an earlier version carry no provenance file and are
  rechecked only after `mix deps.clean --build` or a clean `_build`.
* Root rotation follows TUF: an intermediate root that expired after a
  newer one was adopted no longer ends the chain; only the root in use
  must be unexpired. Before, v1 -> v2 -> v3 fell back to v1 once v2
  expired, which with the version floor failed every run.
* The adopted root version is kept and never goes back (the error names
  the `root_version` file to delete to accept an older root); a trust-state
  file that exists but will not parse is warned about and treated as 0.
* On a device, the Nerves system is read from `/usr/lib/os-release`; the
  loaded-application lookup never matched because systems are `runtime:
  false`, so devices only got pure-Elixir hits.
* Extracted from nerves PR #1220: `Precompiled.Host.run/1` is the build-time
  step `nerves` calls; `Config`, `Match`, `Trust` and `Fetch` moved unchanged
  apart from their HTTP client and output.
* New: `Precompiled.Host.install/2`, `Mix.install/2` with the precompiled
  step in front of it, for use on a device.
* Config moved to `config :precompiled, source: ...`; the
  `config :nerves, :precompiled` form still works.
* On a device, a dependency already compiled in the `Mix.install/2` project
  is no candidate again: a second boot with a cached install re-places
  nothing and works offline. Builds this library installed there are
  rechecked against the batch, so such a boot fetches the root and batch.
* Every HTTP request has an overall deadline (300 s by default) on top of
  the inactivity timer, so a server that keeps dripping data cannot hold a
  build or a boot open.
* `precompiled` never installs a portal build of itself.
* Renamed to `precompiled`; old config keys and `NERVES_PRECOMPILED*`
  variables still work for one release.
* Reads manifest format 2: a version lists its builds, each with a target
  (`pure_elixir` or a Nerves system) and the toolchain it was made with.
  Format 1 manifests still work.
* Matching rules: the running Elixir must have the build's minor and at
  least its patch (pre-releases compare as older), the OTP major must be
  equal, and the dependency's compile env (`dep_env`, `prod` unless the
  project overrides it with `env:`) must equal the build's. Among passing
  builds the closest Elixir patch wins, then `pure_elixir`, then the newest
  run.
* `report.json` carries `"format": 1`.
* Ships as a Mix archive (`mix archive.install github
  TomHoenderdos/elixir_precompiled`) so Livebook and scripts can call
  `Precompiled.Host.install/2` in place of `Mix.install/2`; CI builds it.
* The file cache moved from `~/.nerves/precompiled` to the user cache dir
  (`:filename.basedir(:user_cache, "precompiled")`,
  `~/Library/Caches/precompiled` on macOS, `~/.cache/precompiled`
  on Linux). The old directory is not migrated, so the first run after
  upgrading downloads everything again; set
  `PRECOMPILED_HOME=~/.nerves/precompiled` to keep using the old one.