Forecastle.Baseline (forecastle v1.0.0)

Copy Markdown View Source

Resolves the baseline used for relup generation and appup checks.

Baseline specs support three sources:

rel:_build/prod/rel/my_app/releases/1.0.0/my_app   # an assembled release
tar:artifacts/my_app-1.0.0.tar.gz                  # a release tarball
ref:v1.0.0                                         # a git ref, built in a worktree

A path without a prefix means rel:. Prefer tar: when the deployed artifact is available. Relups select transitions by version string and cannot verify that a rebuilt baseline matches the deployed code. Use ref: for development or when no shipped artifact remains.

Generated baselines are cached under _build/castle/baselines. Tar entries are keyed by the copied artifact's digest. Git entries are keyed by commit, resolution level, MIX_ENV, MIX_TARGET, and the Elixir and ERTS versions. Work is staged and renamed into place only when complete.

A ref: resolution checks out a linked worktree, builds into the staging directory, then removes only that worktree registration. It sets CASTLE_BASELINE and refuses recursive baseline builds.

:compile resolution builds only compiled modules. :release assembles the complete release. The distinction affects only ref: sources.

Summary

Types

level()

How much of the baseline is needed.

source()

Where the baseline comes from.

t()

A resolved baseline.

Functions

parse!(spec)

Parses a baseline spec into its source and value.

resolve!(spec, level)

Resolves a baseline spec at compile or release level.

spec?(value)

Returns whether a string begins with a recognised baseline scheme.

Types

level()

@type level() :: :compile | :release

How much of the baseline is needed.

:compile yields compiled modules, :release an assembled release. Only :release guarantees a :rel_path.

source()

@type source() :: :rel | :tar | :ref

Where the baseline comes from.

t()

@type t() :: %Forecastle.Baseline{
  level: level(),
  lib_dir: Path.t(),
  rebuilt?: boolean(),
  rel_path: Path.t() | nil,
  source: source(),
  spec: binary()
}

A resolved baseline.

  • :spec - the spec exactly as it was given, for diagnostics
  • :source - which of the three sources it named
  • :level - the level it was resolved at
  • :rel_path - the .rel file without its extension, which is how :systools names a release. nil only for ref: at :compile level, where no release was assembled
  • :lib_dir - the directory holding one directory of compiled modules per application, matched by <lib_dir>/*/ebin
  • :rebuilt? - whether the baseline was rebuilt from source rather than being the artefact that shipped

Functions

parse!(spec)

@spec parse!(binary()) :: {source(), binary()}

Parses a baseline spec into its source and value.

A path without a prefix is treated as rel:. Empty values and unknown schemes raise Mix.Error.

resolve!(spec, level)

@spec resolve!(binary(), level()) :: t()

Resolves a baseline spec at compile or release level.

rel: and tar: return an existing release. ref: builds the revision at the requested level and caches the result.

spec?(value)

@spec spec?(binary()) :: boolean()

Returns whether a string begins with a recognised baseline scheme.