Writing the lock file
In AEL, the Agent Engineering Language, ael pack lock resolves every package that a manifest declares and writes the result to pack.lock, without installing anything.
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, is checked first. - Each package gets the highest version its requirement allows. A version with a suffix after a
-is chosen only when you name it exactly. - One scope uses exactly one version of each package. When two packages need incompatible versions of a third, the command stops and names both dependency paths.
- Features are exactly those requested, with no defaults. When two packages ask for different features of a shared package, it gets the requested features combined, and the report shows any dependency or capability this adds.
- A dependency cycle is refused, and the error names the whole cycle.
- Resolution has fixed limits on the number of packages and links in a scope and on how deep a chain may go. Reaching one is an error, never a partial lock file. The Manifest reference gives the numbers.
The same manifest and the same available versions always give the same lock file.
What the lock file records
Your lock file pins the exact versions you built with, so builds repeat, even offline, and nothing downloads when an app starts. It records, 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 never holds secrets, access tokens or absolute paths. It is generated: never edit it by hand, and keep it with your source files.
Scopes
Each manifest has its own lock file beside it. ael pack lock writes only the lock file of the scope it acts on. Two folders can use different versions of one package only when those versions can work side by side in one program; when they cannot, the conflict is reported with both paths.
What it never does
ael pack lock installs nothing, changes no .package/ folder and runs no package code. To resolve versions, it may fetch the registry's signed index and package files; every file it relies on is 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.