Writing the lock file
In AEL, the Agent Engineering Language, ael pack lock (command names may change before launch) will resolve every package that a manifest declares and write the result to pack.lock, without installing anything.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
Usage
ael pack lock
ael pack lock --scope src/api
ael pack lock --json
| Option | Meaning |
|---|---|
--scope <folder> | Lock that folder's manifest. Without it, the manifest that covers the folder you are in. |
--json | A machine-readable report of what was resolved. |
Use it after you edit pack.ael by hand, for example to declare a private package or to change a requirement, and when you want to review a new lock file before anything is installed.
How versions are chosen
- The toolchain requirement in
pack.ael, if there is one, will be checked first. - Each package will get the highest version its requirement allows. A pre-release will be chosen only when you name it exactly.
- One scope will use exactly one version of each package. When two packages need incompatible versions of a third, the command will stop and name both dependency paths.
- Features will be exactly those requested, with no defaults. When two packages ask for different features of a shared package, it will get the requested features combined, and the report will show any dependency or capability this adds.
- A dependency cycle will be refused, and the error will name the whole cycle.
- Resolution will have fixed limits on the number of packages and links in a scope and on how deep a chain may go. Reaching one will be an error, never a partial lock file. The Manifest reference gives the numbers.
The same manifest and the same available versions will always give the same lock file.
What the lock file records
Your lock file will pin the exact versions you built with, so builds repeat, even offline, and nothing will download when an app starts. It will record, for its scope:
- the exact version, origin, publisher and fingerprint of every package, direct or not;
- how the packages depend on each other;
- the features and targets chosen;
- the manifest and project it belongs to.
It will never hold secrets, access tokens or absolute paths. It will be generated: never edit it by hand, and keep it with your source files.
Scopes
Each manifest will have its own lock file beside it. ael pack lock will write only the lock file of the scope it acts on. Two folders will be able to use different versions of one package only when those versions can work side by side in one program; when they cannot, the conflict will be reported with both paths.
What it never does
ael pack lock will install nothing, change no .package/ folder and run no package code. To resolve versions, it may fetch the registry's signed index and package files; every file it relies on will be verified first.
Related
- Installing declared packages: installing what the lock file records.
- Comparing lock files: reviewing a new lock file against the old one.
- Manifest reference: version requirements.