Building a package

With AEL, the Agent Engineering Language, you build a package with the ael package command, which produces a single package file. Your own libraries ship compiled, without your source.

ael package builds a package; ael pack manages the packages a project uses. Keep the two apart.

Usage

ael package
ael package <folder> -o <file>

Argument or option	Meaning
`[folder]`	The project to package. Without a folder, the project in the current folder.
`-o <file>`	Where to write the package file.
`--json`	A machine-readable report, with any diagnostics.

What the project needs

A package is built from an ordinary project, with main.ael, pack.ael and metadata.ael at its root. Its metadata.ael has to name the package:

metadata {
    schema = 1;
    name = "acme/billing";
    description = "Billing checks for support agents";
}

A package name is lower case and slash-separated, such as acme/billing, and at most 128 characters.
The description is optional.
Without a package name, ael package stops before it writes anything.

It then checks the whole project as ael check does: files and roles, limits, names, visibility, hooks, targets and the locked packages the project itself uses.

What goes into the file

Compiled AEL for every component of the project, including exports that main never calls. A package keeps every public export: a GET handler, a PUT handler and a reusable function all stay, even when nothing in the package connects them.
A description of each export, so a project that uses the package can check its calls, and build its reference map, without your source.
Nothing else. No source, no comments, no scripts and no native code.

Your helper functions stay private: they are compiled into their component, and no project that uses the package can call them. Packages your project depends on are not copied in: the file records each one by its exact identity, and a project that uses your package gets them through its own lock file.

Every AEL package, from OpenEng or from you, is written in AEL and ships as compiled, verified AEL, with no bundled native code and no install scripts.

What it never does

It never runs main: packaging is not a program build, and nothing is left out because main does not reach it.
Nothing in the file runs when a project installs it.

The same project produces the same package file, so two builds of one version can be compared by their fingerprints.

Hosting your package

You host that file yourself: as a release download in your own GitHub or GitLab project, at any https address, or inside your project. Your project records the file's address and fingerprint, and AEL refuses the file if it ever changes. Access tokens for your private host stay outside your project files.

A project that uses your package declares it with an https or local source and the file's fingerprint:

{ name = "acme/billing"; version = "=0.3.1"; kind = "runtime"; publisher = "acme";
  source = { kind = "https";
             url = "https://git.example.com/acme/billing/releases/download/v0.3.1/acme-billing-0.3.1.zip";
             digest = "sha256:<64 hex digits>"; };
  features = []; targets = []; capabilities = []; }

Only OpenEng publishes to the official registry, and the official registry never hosts or lists private packages. Using packages and the Manifest reference describe how a project uses your file.

Creating a package: what goes into a package file, and what it exports.
Private packages: hosting the file and using it from other projects.
Package commands: managing the packages a project uses.