magus v0.4.3 is out. See what's new
¶ View generated markdown
2 min read

podman

The podman spell forks the podman CLI. It is separate from docker rather than a bin substitution because podman has no buildx: multi-platform images are podman build --platform plus podman manifest, so the two runtimes need different ops rather than the same ops with a different binary.

Runtime name: podman (source spells/podman/)

Version probe (podman): podman --version

Passing arguments to ops

Every op is invoked as podman["<op>"](ctx, opts?). The first argument is the target's context, which is what carries the execution environment; the optional options map shapes the command itself:

Key Type Description Source
args [str] Extra arguments appended to the resolved command, replacing any trailing defaults the op declares (go-test's ./...), so passing args also states the scope. Omit it and a bare podman["<op>"]() keeps the defaults and forwards magus run <target> -- <extra> to the tool automatically; pass it to set the arguments explicitly, which replaces that passthrough. To keep the passthrough too, append the target's own args parameter: {"args": ["-race", "./..."] + args}. source
stdin str Data written to the command's standard input. source

Working directory and environment are NOT options: they ride the context, as podman["<op>"](ctx.withCwd("sub")) and podman["<op>"](ctx.withEnv({"CGO_ENABLED": "0"})). Only the context reaches the cache key, so an option-table cwd or env would change what the tool did while the key said otherwise; passing either as an option is an error.

Charms (the :charm suffix, e.g. magus run test:rw) are orthogonal: they patch the base argv, while these options add to it. See Charms.

machine

The machine is the Linux VM podman runs containers in on macOS and Windows. It outlives podman machine start, so it is a start service: already running, magus adopts it and never stops it; started by magus, it is stopped after 30 minutes with no holder. On Linux podman info passes at once, so the machine is adopted and never touched.

Command: podman machine start

podman-build

Command: podman build

podman-manifest

Multi-platform images without buildx: build per-arch, then assemble and push a manifest list. The caller supplies the list name and members through args.

Command: podman manifest

podman-push

podman push is its own verb; docker reaches the same place through buildx --push. mutates-external because the effect lands in a registry: a target that replayed this would report a delivery that never happened. docker-buildx is deliberately NOT marked, because it pushes only when the caller passes --push, and an op that reaches outward half the time cannot answer this question for the target composing it.

Command: podman push

podman-run

--rm is baked in for the same reason the docker spell bakes it in: an op that leaves containers behind turns a repeated target into a disk leak.

Command: podman run --rm

SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus. ADR 0003: running an invocation on another operating systemWhether magus should learn to run an invocation on a kernel other than the host's, so a macOS checkout can reproduce a Linux-only failure (landlock, /proc, the unix socket path limit) before CI does. Decides one Engine-API client reached through one user fact, a top-level --platform flag that relays the whole invocation, and symbol indexers that always run from their spell's image; records the prefix script and the provider-spell flag as considered; lists what the reviewers found and how each finding is answered. Writing a spellAuthor a magus spell (the mgs_ contract functions, toolchain spells that contribute operations, and provider spells that back the remote cache, CI annotations, or secret resolution).
generatedspells/podman/spell.buzzpodmanspellcontainerimageocibuildahtools
Last updated (1a76274f)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Manifest

The file that declares what a package is: its name, dependencies, entry points and tool config (go.mod, package.json, pyproject.toml, Cargo.toml). How the workspace builds, tests and lints the package belongs in the magusfile, not in the manifest's scripts. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. See wards.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs: magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Window

The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Conventions

Placeholders

Angle brackets mark a value you replace with your own; never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.