Adding a package
oel pack add adds a package the project does not already use. In one change, it writes the new entry into pack.oel, resolves the package and its dependencies, verifies them, writes pack.lock and installs them into .package/.
Usage
oel pack add server/http
oel pack add server/http@1.2.3
oel pack add math/linalg --scope src/analysis
| Argument or option | Meaning |
|---|---|
<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. |
--json | A machine-readable report of the change. |
Before anything changes
oel 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.lockrecords 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.oel, 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.
Packages that are not yet on this machine
By default, oel pack add installs from an offline catalog on your machine. With --download and --catalog <dir>, it also fetches an archive the catalog lacks, over HTTPS, from the origin the lock file records, and stores it only when it matches the digest the lock file pins. Installing declared packages lists the options and the limits that apply.
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
oel pack repairrestores it. - Nothing in a package runs while it is added.
To change a package the scope already declares, use oel pack update. To set up packages that are already declared and locked, such as on a new machine, use oel 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.oel, as the Manifest reference shows, then set it up with oel pack lock and oel pack install.
Related
- Package commands: the rules every package command shares.
- Using packages: adding, installing, updating and removing packages.
- Package catalog: the families of official packages.