Packages: add, update and offline builds

Step 1: add a package to the project

ael pack add server/http@1.2.3

ael pack add adds a package that is new to the project: it declares it in the root pack.ael, resolves it, installs it and writes pack.lock, all at once. Before anything changes, it shows the dependencies and capabilities the package brings. AEL verifies every package before using it, whatever its host: its fingerprint, its contents and how it was built.

Step 2: add a package to one folder

Each folder of a project can add its own packages without affecting the rest:

ael pack add math/linalg --scope src/analysis

support/
  pack.ael            # server/http for the whole project
  pack.lock
  src/
    analysis/
      pack.ael        # math/linalg for src/analysis and below
      pack.lock

• add, install, update, remove, lock and list take --scope <folder> to choose which folder's manifest they act on; without it, they use the manifest that covers the folder you are in.
• The nearest manifest that declares a package wins, and a folder's manifest adds packages; it never hides the ones declared further up.
• Every change reports the scope it acted on.

Step 3: select what you use

A file names the exports it uses in its header:

refer server/http select get;

You select exactly the exports you use, and the compiler flags selections you never use: selecting get, put and using only get fails the check.

Step 4: install on another machine

Keep pack.lock with your source files and leave .package/ out. On a new machine:

ael pack install --locked
ael pack verify

ael pack install installs exactly what pack.ael and pack.lock already say and changes no version; --locked refuses to change the lock file. ael pack verify checks the installed packages against it. Your lock file pins the exact versions you built with, so builds repeat, even offline, and nothing downloads when an app starts.

Step 5: update and remove

ael pack update server/http
ael pack why math/linalg
ael pack remove math/linalg --scope src/analysis

• ael pack update moves a package to another version its requirement allows, and shows what else changes.
• ael pack why explains why a package is in the project, and through which path.
• ael pack remove keeps the packages that others still need, and never edits your source: if a file still refers to the package, the next check names the reference.

Adding, installing, updating and removing packages are atomic and safe to roll back, and a package never runs an install script. An interrupted change leaves the complete old state or the complete new one, never a mix.

Step 6: build without a network

On a machine that has the packages:

ael pack vendor -o vendor

Copy the project, its pack.lock and the vendor folder to the machine without a network, then:

ael pack install --locked --offline
ael build --target <target> -o build/support --release

Every package file is verified again against the fingerprint in the lock file before it is installed. --offline uses verified local copies only and names any package file that is missing. Checking, compiling and building use only the locked, installed packages: they never contact the registry, change a version or install anything.

Step 7: tidy the cache

ael pack cache prune

ael pack cache prune removes cached packages that no project uses, and never touches source.

Honest limits

• Two folders can use different versions of one package only when those versions can work side by side in one program; otherwise AEL reports the conflict instead of picking one.
• ael pack vendor exports only verified copies already on your machine: run ael pack install --locked first where a copy is missing.
• The version numbers in these examples are illustrative.