Browse the documentation

Early preview

Packages: add, update and offline builds

In the Open Engineering Language, one manifest and one lock file give reproducible builds that also work offline. This tutorial adds a package to a whole project and another to one folder, installs a project on a second machine, updates and removes a package, and builds where there is no network.

Step 1: add a package to the project

oel pack add server/http@1.2.3

oel pack add adds a package that is new to the project: it declares it in the root pack.oel, resolves it, installs it and writes pack.lock, all at once. Before anything changes, it shows the dependencies and capabilities the package brings. The Compiler verifies every package before using it, whatever its host: its fingerprint, its contents and how it was built.

Step 2: add a package to one folder

Each folder of a project can add its own packages without affecting the rest:

oel pack add math/linalg --scope src/analysis
support/
  pack.oel            # server/http for the whole project
  pack.lock
  src/
    analysis/
      pack.oel        # math/linalg for src/analysis and below
      pack.lock
  • add, install, update, remove, lock and list take --scope <folder> to choose which folder's manifest they act on; without it, they use the manifest that covers the folder you are in.
  • The nearest manifest that declares a package wins, and a folder's manifest adds packages; it never hides the ones declared further up.
  • Every change reports the scope it acted on.

Step 3: select what you use

A file names the exports it uses in its header:

refer server/http select get;

You select exactly the exports you use, and the Compiler flags selections you never use: selecting get, put and using only get fails the check.

Step 4: install on another machine

Keep pack.lock with your source files and leave .package/ out. On a new machine:

oel pack install --locked
oel pack verify

oel pack install installs exactly what pack.oel and pack.lock already say and changes no version; --locked refuses to change the lock file. oel pack verify checks the installed packages against it. Your lock file pins the exact versions you built with, so builds repeat, even offline, and nothing downloads when an app starts.

Step 5: update and remove

oel pack update server/http
oel pack why math/linalg
oel pack remove math/linalg --scope src/analysis
  • oel pack update moves a package to another version its requirement allows, and shows what else changes.
  • oel pack why explains why a package is in the project, and through which path.
  • oel pack remove keeps the packages that others still need, and never edits your source: if a file still refers to the package, the next check names the reference.

Adding, installing, updating and removing packages are atomic and safe to roll back, and a package never runs an install script. An interrupted change leaves the complete old state or the complete new one, never a mix.

Step 6: build without a network

On a machine that has the packages:

oel pack vendor -o vendor

Copy the project, its pack.lock and the vendor folder to the machine without a network, then:

oel pack install --locked --offline
oel build --target <target> -o build/support --release

Every package file is verified again against the fingerprint in the lock file before it is installed. --offline uses verified local copies only and names any package file that is missing. Checking, compiling and building use only the locked, installed packages: they never contact the registry, change a version or install anything.

Step 7: tidy the cache

oel pack cache prune

oel pack cache prune removes cached packages that no project uses, and never touches source.

Honest limits

  • Two folders can use different versions of one package only when those versions can work side by side in one program; otherwise the Compiler reports the conflict instead of picking one.
  • oel pack vendor exports only verified copies already on your machine: run oel pack install --locked first where a copy is missing.
  • The version numbers in these examples are illustrative.