Browse the documentation

Early preview

Private packages

A private package in the Open Engineering Language is a package file you build and host yourself. You build a package with the oel package command, which produces a single package file. 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 the Compiler refuses the file if it ever changes. Access tokens for your private host stay outside your project files.

How it works

  1. Build the package file with oel package; see Creating a package.
  2. Host it where the projects that use it can reach it.
  3. Record it in the pack.oel of each project that uses it: its address or path, and its fingerprint.
  4. Lock and install: oel pack lock writes the lock file and oel pack install installs it. From then on, the package works like any other: offline, pinned by the lock file, and verified.
Where you host the fileSource kind
A release download in your own GitHub or GitLab projecthttps
Any other https address that never changeshttps
A file kept inside the project that uses itlocal

Your project always points to a built package file. The Compiler never builds a package from source when it installs it.

A package file at an https address

{ 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 = []; }
  • The address uses https, and it points at one file that never changes: the download for one version, never a link that moves to the newest one.
  • The address carries no user name, password, query or fragment.
  • The file has to match the fingerprint every time it is fetched. If the file at the address ever changes, the Compiler refuses it.
  • If your host redirects the download, the Compiler never sends your access token to a different host.

A package file inside your project

{ name = "acme/billing"; version = "=0.3.1"; kind = "runtime"; publisher = "acme";
  source = { kind = "local";
             path = "vendor/acme-billing-0.3.1.zip";
             digest = "sha256:<64 hex digits>"; };
  features = []; targets = []; capabilities = []; }
  • The path is relative to the project root and uses /. It stays inside the project: no .., no absolute paths and no links that lead outside.
  • It is always a built package file, never a folder of source. To change the package, build a new file with oel package, replace the old one, and update the fingerprint.

The fingerprint

The digest field is the file's fingerprint: its SHA-256 value, written sha256: followed by 64 lower-case hex digits. It is computed over the file's bytes, so any standard SHA-256 tool gives the same value.

A fingerprint proves that the file is the one you recorded. It does not prove who made the file: that is your decision when you add a private package from someone else.

Access tokens

Access tokens for your private host stay outside your project files. They are never written to your manifest, your lock file, a package file or the Compiler's output, and never sent to the official registry.

A new version

  1. Build the new version with oel package.
  2. Host it at a new address, or at a new path inside the project.
  3. Update version, url or path, and digest in each project that uses it.
  4. Run oel pack lock and oel pack install.

Leave the old file where it is, so projects still locked to it can install it again, for example on a new machine.

Kept apart from the official registry

  • The official registry never hosts or lists private packages, and you cannot upload to it.
  • The Compiler never treats an external package as an official one, even if its name matches. A private package's publisher is your own name, never openeng.
  • If a private package cannot be reached, the Compiler never falls back to an official package of the same name.
  • The Compiler verifies every package before using it, whatever its host: its fingerprint, its contents and how it was built. See Security and provenance.