AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

AEL 1.0.0

Adding a package

In AEL, the Agent Engineering Language, ael pack add adds a package the project does not already use. In one change, it writes the new entry into pack.ael, resolves the package and its dependencies, verifies them, writes pack.lock and installs them into .package/.

Usage

ael pack add server/http
ael pack add server/http@1.2.3
ael pack add math/linalg --scope src/analysis
Argument or optionMeaning
<name>The package name, such as server/http.
@<version>Optional: the version you want.
--scope <folder>Add the package to that folder's own manifest. Without it, the manifest that covers the folder you are in.
--jsonA machine-readable report of the change.

Before anything changes

ael pack add shows what the change brings before it makes it:

  • the package and the exact version it resolved;
  • every other package it brings with it, direct or not;
  • the capabilities each package asks for, such as "net.listen".

A capability in a manifest is a request, never a grant: your deployment still decides what a program may do.

What it writes

The new entry names every field explicitly, as every dependency does. For example, with an illustrative version requirement:

{ name = "server/http"; version = "^1.2.0"; kind = "runtime";
  source = { kind = "registry"; };
  features = []; targets = []; capabilities = ["net.listen"];
  publisher = "openeng"; }
  • The package gets no features unless you list them: there are no default features.
  • The version chosen is the highest that the requirement allows.
  • pack.lock records the exact version, origin and fingerprint of every package the scope now uses, so builds repeat, even offline.

Scopes

With --scope <folder>, the package is added to that folder's pack.ael, and only that folder and the folders below it use it. Each folder of a project can add its own packages without affecting the rest. If the folder has no manifest, the command can create one there. Nothing outside that scope changes.

Checks and safety

  • Every package is verified before anything is written: its signature for official packages, its fingerprint, its contents and how it was built.
  • The whole change is atomic: if it fails or is interrupted, the scope stays exactly as it was, or ael pack repair restores it.
  • Nothing in a package runs while it is added.

To change a package the scope already declares, use ael pack update. To set up packages that are already declared and locked, such as on a new machine, use ael pack install.

After adding

A package does nothing until a file selects the exports it uses:

refer server/http select get;

Every selected export has to be used. See Using packages.

Private packages

You declare a private package by writing its entry in pack.ael, as the Manifest reference shows, then set it up with ael pack lock and ael pack install.