Browse the documentation

Early preview

Installing declared packages

oel pack install sets up the packages a project already declares, exactly as pack.oel and pack.lock say, changing no version. It is what you run on a new machine, or at the start of an automated build.

To add a package the project does not already use, use oel pack add.

Usage

oel pack install
oel pack install --locked
oel pack install --locked --offline
oel pack install --scope src/api
OptionMeaning
--lockedRefuse to change pack.lock. If it no longer matches pack.oel, stop and change nothing.
--offlineUse no network: install only from verified copies already on this machine.
--scope <folder>Install for that folder's manifest. Without it, the manifest that covers the folder you are in.
--jsonA machine-readable report.

What it does

  • It reads the scope's pack.oel and pack.lock, and installs every package the lock file names, direct or not, into .package/ beside them.
  • It never moves a version that pack.lock records.
  • It never builds a package from source, runs an install script or runs any package code.
  • It installs into this scope only, never into a parent or sibling folder.

Your lock file pins the exact versions you built with, so builds repeat, even offline, and nothing downloads when an app starts.

Locked installs

--locked is the mode for automated builds and new machines. With it, oel pack install never writes pack.lock: if the lock file is missing, or no longer matches its manifest, the command stops with an error that says so, and nothing changes.

Keep pack.lock with your source files and leave .package/ out: oel pack install --locked recreates it from the lock file alone.

Offline installs

With --offline, nothing is fetched. Packages come only from verified copies already on your machine, such as the shared package cache. If a package file is missing, the command names each missing file and installs nothing.

Downloading missing archives

By default nothing is fetched. With --download, oel pack install fetches a package archive that your offline catalog does not hold, over HTTPS, from the origin the lock file records for it:

oel pack install <project> --catalog <catalog> --download
oel pack install <project> --catalog <catalog> --download --tls-roots roots.pem --max-download-bytes 33554432
OptionMeaning
--catalog <dir>The offline catalog. A downloaded archive is stored in its archives folder, where the ordinary offline install reads it.
--downloadAllow downloading the archives the catalog lacks.
--tls-roots <file>The root certificates to verify servers against. Without it, the system's certificate bundle.
--credential <host>=env:<name> or <host>=file:<path>A token for one host, read from an environment variable or from a file that only you can read. It is sent to that host alone and is never written to the lock file, a report or a diagnostic.
--redirect-host <host>Another host a redirect may reach. Repeat the option for each host.
--connect-to <host>=<address:port>Connect to that address for the host, for a mirror or a local test server. The certificate is still checked against the host name. Repeat the option for each host.
--max-download-bytes <n>The most one archive may have. It never exceeds the 64 MiB limit of a package archive.
--download-timeout <seconds>The most time one archive may take. The default is 600 seconds.
--download-retries <n>How many more attempts a failed transfer gets, each resuming the partial file. The default is 2.
--cancel-file <file>Stop the transfer when this file appears.
  • The lock file decides what is fetched. A registry archive is fetched from the origin the lock file records; an archive from an https source, from exactly the address that source names.
  • Nothing is trusted until it matches. The complete file must have exactly the SHA-256 the lock file pins before it is stored. Otherwise the project and the catalog are left as they were.
  • HTTPS only. Servers are verified against the root certificates. An address with a user name, a port or a fragment is refused, and so is any redirect to http:// or to a private address. A redirect may reach only the origin host, a host you name with --redirect-host, or the hosts GitHub serves release files from, and at most four redirects are followed.
  • A transfer is bounded. A transfer that sends no byte for 30 seconds fails. A partial file is resumed instead of starting over.

A download that fails is reported as PACK_INSTALL_DOWNLOAD with its cause: canceled, over the time limit, idle, over the size limit, a digest that differs, a certificate or credential that is refused, or a redirect or address the policy refuses. The report of a successful install marks each archive it downloaded.

oel pack add, oel pack update and oel pack remove take the same options when they need an archive the catalog lacks.

Checks and safety

  • Every package file is verified before it is used: its signature for official packages, its fingerprint against the lock file, its contents and how it was built.
  • The whole install is atomic: the scope is either as it was or fully installed, never half of each. An interrupted install is finished or undone by the next package command, or by oel pack repair.
  • Access tokens for your private host stay outside your project files.