AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

Preview documentation for AEL Beta 0.0.1 — launching soon

Adding a package

In AEL, the Agent Engineering Language, ael pack add (command names may change before launch) will add a package the project does not use yet. In one change, it will write the new entry into pack.ael, resolve the package and its dependencies, verify them, write pack.lock and install them into .package/.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

Package names on this page are preview naming and may change before launch.

Usage

Preview syntax — may change before launch
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 will show 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 will be a request, never a grant: your deployment will still decide what a program may do.

What it writes

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

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

Scopes

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

Checks and safety

  • Every package will be verified before anything is written: its signature for official packages, its fingerprint, its contents and how it was built.
  • The whole change will be atomic: if it fails or is interrupted, the scope will stay exactly as it was, or ael pack repair will restore it.
  • Nothing in a package will run 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 will do nothing until a file selects the exports it uses:

Preview syntax — may change before launch
refer server/http select get;

Every selected export will have to be used. See Using packages.

Not settled yet

How @<version> is written into the new requirement, and how ael pack add will take a private package from an https or local source, will be confirmed before launch. You will always be able to 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.