Migrating a project
In AEL, the Agent Engineering Language, changes to the language or the project format come with explicit, reviewable migrations. ael migrate is the command that applies them. By default it only prints its plan; it writes only when you add --apply, and it keeps what it needs to undo every change.
Usage
ael migrate PROJECT
ael migrate PROJECT --apply
ael migrate PROJECT --apply --compare-run
ael migrate PROJECT --rollback
ael migrate PROJECT --roots --name NAME --apply
ael migrate --matrix
| Option | Meaning |
|---|---|
--apply | Write the changes. Without it, the command prints the plan and changes nothing. |
--json | The plan or report in machine-readable form. |
--global FUNCTION | When converting an older project: make this function a shared function of its folder instead of a reusable one. Repeat it for several functions. |
--compare-run | With --apply: run the project natively before and after, and restore the original when the results differ. |
--run-with PATH | With --compare-run: run both sides with the ael program at this absolute path, for example a release build, instead of the one you are running. |
--rollback | Restore the project as it was before the migration. |
--roots | Add the root files a loose main.ael project lacks. |
--name NAME | With --roots: the application name for the new metadata.ael. |
--matrix | Print what the migrations support, what they refuse and what you must do by hand. |
Naming the application
The main function carries the name of the application: main NAME() -> i64, where NAME is the name in metadata.ael. ael migrate PROJECT plans the rewrite of an entry still named main to that name, shows the exact lines it would change and, with --apply, writes them. It refuses a project whose metadata.ael has no name. The built program takes the same name by default.
Converting an older project
An older project that holds an ael.project.json file is converted to the current source format, with one file for each public function. A function becomes a reusable function by default, with the imports its callers need; name it with --global to make it a shared function of its folder. The command shows each function's mapping, checks that its body and its calls are kept, and refuses what the folder rules of the current format cannot express, with the reason for each refusal. Test fixtures of the old format are listed and kept only in the rollback copy.
Comparing results
With --apply --compare-run, the project runs natively before the change and again after it. When both runs give the same output, the report records the output's digest. When they differ, or the migrated project no longer runs, the original files are restored and the command refuses. When the project does not run before the migration, there is nothing to compare, and the report says the comparison is unavailable instead of claiming equality.
Rolling back
Applying a migration stores a copy of each file it changes in a rollback folder inside the project. ael migrate PROJECT --rollback restores them, and refuses to do so when one of the migrated files has been edited since, so your later changes are never overwritten.
Adding the root files
A folder with only a main.ael lacks the two other root files. ael migrate PROJECT --roots plans the pack.ael and metadata.ael that a new project would receive and, with --apply, adds them. It never changes main.ael or a root file that exists, and it removes the new files again when the project does not check afterwards.
Related
- Project layout: the root files and the files of a project.
ael check: checks the project a migration produced.ael fmt: formats the migrated files.- Releases: what changed in each release, and which migration it needs.