Building a package

ael package will build a package; ael pack will manage the packages a project uses. Keep the two apart.

Usage

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

What the project needs

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

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

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

It will then check 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 will keep every public export: a GET handler, a PUT handler and a reusable function will 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 will stay private: they will be compiled into their component, and no project that uses the package will be able to call them. Packages your project depends on will not be copied in: the file will record each one by its exact identity, and a project that uses your package will get them through its own lock file.

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

What it never does

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

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

Hosting your package

You will 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 will record the file's address and fingerprint, and AEL will refuse the file if it ever changes. Access tokens for your private host will stay outside your project files.

A project that uses your package will declare 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 will publish to the official registry, and the official registry will never host or list private packages. Using packages and the Manifest reference describe how a project uses your file.

Not settled yet

Where the package's version is recorded, and how the package file is named by default, will be described when the project metadata format is final.

Related

• 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.