magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

MGS1017: magusfile is not a spell

A magusfile imported magus/spell/magusfile, or named magusfile in its project's "spells" list. Neither has any effect: magus binds that driver to every project it discovers.

A spell is a library of tool-native operations for one toolchain - the go spell exposes go-build/go-test/go-vet, the rust spell exposes cargo-build/cargo-clippy. The magusfile driver adapts no toolchain and contributes no operations. It is what makes the targets in the file you are writing runnable at all, which is not something an author opts into.

Resolution

Delete the import, and drop magusfile from the "spells" list:

 import "magus";
-import "magus/spell/magusfile";
 import "magus/spell/go";

 magus\project({
-    "spells": [magusfile, go],
+    "spells": [go],
 });

A project whose targets all come from its magusfile binds no toolchain at all, so it needs no list:

 magus\project({
-    "spells": [magusfile],
 });

Your targets keep running exactly as before. magus ls will stop reporting spell: magusfile for the project and report the toolchain it actually binds, or none.

Why this is an error rather than a warning

Binding the driver became implicit because listing it was never the author's job. That left the import and the list entry as no-ops which still taught every reader - and every generated example - that magusfile was a spell like go or buf. Failing loudly with the one-line fix ends that, rather than leaving a declaration that looks load-bearing and is not.

MGS1017magusfilespellsmigrationbreaking-change
Last updated (b529b75f)
Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

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.

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.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

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

This page uses none of the site's convention markers. The full set is on the conventions page.