mix castle.relup (forecastle v1.0.0)

Copy Markdown View Source

Generates a relup for an existing target release.

mix castle.relup --target <path> --fromto <spec>

For a release being assembled now, prefer upgrade_from: with Castle.customize/1; Forecastle then writes the relup immediately before :tar. Use this task for an existing target, separate upgrade and downgrade baselines, explicit strategies, or a dry run.

Options

  • --target names the target .rel path without the extension.
  • --fromto generates both directions from a baseline.
  • --upfrom generates only an upgrade from a baseline.
  • --downto generates only a downgrade to a baseline.
  • --outdir selects an existing output directory. It defaults to the current directory.
  • --hot requires every transition to remain hot.
  • --restart makes every transition restart the emulator.
  • --dry-run validates and reports the plan without writing the relup.

Supply at least one baseline switch. --hot and --restart are mutually exclusive.

Baselines

Baseline switches accept three sources:

rel:_build/prod/rel/my_app/releases/1.0.0/my_app
tar:artifacts/my_app-1.0.0.tar.gz
ref:v1.0.0

A path without a prefix means rel:. rel: names an assembled release, tar: unpacks a release artifact, and ref: builds a git revision. Prefer tar: when the shipped artifact is available because a rebuilt baseline may differ from the deployed code.

--target is always a path, not a baseline spec.

The task writes a complete relup through a staging file. A failed generation leaves any existing output untouched. Use the default output directory when a later release build should package the project-root relup.

Strategies

auto, the default, keeps a transition hot unless the ERTS changes or an unowned application changes version without a matching appup. Upgrade and downgrade directions are classified separately. A missing appup for an owned application remains an error. Added and removed applications remain hot.

--hot rejects a missing appup, ERTS change, or appup instruction that would restart the emulator. Use it for pipelines that require hot deployment.

--restart emits a single restart_emulator instruction for each transition. It does not read appups or call :systools.

Forecastle reports every restart edge and its reason. It supports only the one-stage restart_emulator transition and rejects restart_new_emulator, including instructions introduced by appups.

Dry runs

--dry-run resolves baselines and generates the complete plan without publishing the relup. Its exit status reports whether generation succeeded. It cannot detect a destination write failure.

Baseline resolution may still write to _build/castle/baselines: tar: unpacks an artifact and ref: builds a revision. The relup and output directory remain untouched.