Skip to content

Environment composition

How OCX assembles environment variables and selects the active toolchain. The reasoning behind each rule is in Environments and Toolchain activation.

Strict Isolation

Global packages never compose into, supplement, or fall back into a project’s resolved environment. Both env-composition commands compose only the packages they were asked for: an undeclared package is never filled in from the global toolchain.

Command Tier Reads
ocx exec Project ocx.toml and ocx.lock
ocx package exec OCI OCI identifiers on the command line, never any ocx.toml

See Strict isolation.

PATH precedence

Isolation is PATH order and not PATH stripping: a project’s binaries are prepended ahead of the global toolchain’s and shadow same-named global binaries. ocx direnv export emits only the project’s PATH entries, which direnv prepends before the ambient PATH.

See PATH precedence.

Idempotent re-application

Every PATH prepend OCX emits is idempotent with move-to-front semantics: a directory already present moves from its old position to the front. Re-applying the same output therefore never grows PATH.

  • Output: self-contained shell statements, with no dependency on an ocx process, a guard variable or a helper function
  • Shells: bash, zsh, ash, ksh, dash, fish, PowerShell, elvish, nushell, Windows cmd
  • Version floors: elvish 0.16+ (str: module), nushell 0.101+ (auto-list PATH conversion)
  • cmd: rebuilds PATH with %VAR:search=% substring deletion, with no FOR /F and no delayed expansion, and matches segments case-insensitively
  • Also applies to: the in-process environment of ocx exec and ocx package exec, and to CI exports (--ci=github, --ci=gitlab)

See Idempotent re-application.

Layered ocx exec

ocx exec reads exactly two files, ocx.toml and its sibling ocx.lock, and composes only the packages they declare. It layers them over the caller’s environment, prepending the composed PATH entries and setting the other composed variables on top.

  • Default: the caller’s environment, unchanged underneath the layer
  • --isolate: reverts what earlier OCX layers applied before composing, and your own pre-existing values stay
  • --clean: starts from an empty environment, so only package-declared variables reach the child (on Windows, plus the caller’s SystemRoot, without which a process cannot start)
  • --isolate --clean: a usage error (exit 64)
  • Explicit exec: always composes what it was asked for, whatever is already loaded. The same project and group nested yields each value once, and another group layers on top
  • Named bindings: ocx exec node -- … resolves only the named bindings to a host leaf. Omit the names and the whole scope must resolve
  • -g GROUP: selects the namespace for name resolution, not a mandate that every binding in it be available
  • Revert source: --isolate reads the applied values recorded in __OCX_ENV_STATE. A value that no longer matches what OCX wrote is left alone, and with no state there is nothing to revert
  • Same flags: ocx shell, ocx package exec, ocx package test and ocx patch test

See Layered ocx exec.

ocx package exec

ocx package exec takes one or more OCI identifiers, resolves each, composes the declared environment variables of the resolved packages over the caller’s environment and spawns the command. No ocx.toml is read, neither the project file nor the global file, and it accepts --isolate and --clean as ocx exec does.

Patch Opt-Out Scope

A project’s no-patches opt-out is read from ocx.toml, so it applies only where the project file is directly in scope. A system-required [patches] section is never subject to it.

Invocation Honors the opt-out How
ocx exec Yes Marks the opted-out packages in the names it records in __OCX_ENV_STATE
ocx env, ocx direnv export Yes Read the project config directly; they and the shell hook mark the opted-out package in the names carried by __OCX_ENV_STATE
Launcher re-entered from those chains Yes Reads the mark from the inherited state
Launcher run by absolute path or through ocx package exec No Decodes no forwarded opt-out and composes the companion overlay as if no-patches were never set

See Per-package opt-out.

Toolchain Selection

OCX has two toolchains, project and global, and selection is always explicit: there is no implicit fallback from project to global. --global and --project are mutually exclusive, and combining them exits with code 64 (UsageError).

Tier How to activate File
Project CWD walk finds ocx.toml; or --project <path>; or OCX_PROJECT nearest ocx.toml ancestor
Global --global flag $OCX_HOME/ocx.toml
  • CWD walk: stops at the first ocx.toml it meets. A nested project replaces the enclosing one, and two project files never layer
  • No home-directory discovery: a walk that finds nothing means no project is active, and the global toolchain is active only when requested

See Nested projects switch, they do not stack.

Root --global commands

--global is a root flag and must appear before the subcommand, as in ocx --global add ripgrep:14. It affects these toolchain commands:

Command With --global
ocx add Adds binding to the global file
ocx remove Removes binding from the global file
ocx lock Re-locks the global file
ocx update Advances a binding in the global file
ocx pull Pre-warms packages declared by the global file
ocx exec Composes env from the global file + its lock
ocx env Emits composed toolchain env for the global file

Toolchain Activation

Two ocx.toml keys decide how a selected toolchain reaches a shell, and both are read per toolchain from that toolchain’s own file. activate picks the shape, and pinned picks whether composed paths follow the rendered links/<group>/<entry> links or name digest paths from ocx.lock.

See Toolchain activation.

The activate × pinned matrix

activate pinned What the project contributes to PATH What a composing emitter composes What ocx pull renders
env false its composed entries — each package’s own PATH directories through the links/<group>/<entry> links the trampolines and the links
env true its composed entries — each package’s own PATH directories digest paths from ocx.lock, consulting no link the trampolines only — the link pass writes and prunes nothing
bin false <home>/toolchain/active/bin, and nothing else through the links/<group>/<entry> links the trampolines and the links
bin true <home>/toolchain/active/bin, and nothing else digest paths from ocx.lock, consulting no link the trampolines only
none false nothing through the links/<group>/<entry> links the trampolines and the links
none true nothing digest paths from ocx.lock, consulting no link the trampolines only
  • Session directories: $OCX_HOME/toolchain/active/bin and OCX’s install directory behind it are on PATH in every row, including none
  • Composing emitters: ocx env, ocx exec, ocx direnv export, the env-mode shell hook and the env-mode login exporter. Only ocx env and ocx exec declare --pinned / --no-pinned
  • env-mode shell hook and login exporter: read the global toolchain’s activate, so under bin or none neither composes at all
  • Link cells: a lock entry whose link is absent, stale or not a link composes on its digest path. Only roots have links, so a dependency’s PATH contributions and every ${deps.<name>.installPath} are digest paths in both lanes. See --pinned
  • pinned = true: suppresses the link pass without deleting a tree, so switching it on and off needs no re-render
  • bin gate: <home>/toolchain/active/bin is added only when the tree’s render marker matches this project and this lock. Otherwise nothing is added and the prompt prints the line below
ocx: /home/dana/work/api: its toolchain has not been rendered for this lock; run `ocx pull` here

Within one prompt the entries land in this order, front to back:

  1. The project’s composed entries
  2. The project’s <home>/toolchain/active/bin
  3. $OCX_HOME/toolchain/active/bin
  4. OCX’s own install directory
  5. The global toolchain’s composed entries

See Order on PATH.

The trampoline body, its Windows sidecar and the name-collision rule are in A trampoline composes at call time and Name collisions.

Visibility Surfaces

Each package declares an interface surface (what consumers see) and a private surface (what its own launchers see). The --self flag on package env, package exec, package test and package deps selects the surface, and it exists only on the ocx package commands.

--self Surface emitted Use case
off (default) Interface surface — public and interface vars Human or CI script using the package
on Private surface — private and public vars Generated launchers invoking ocx launcher exec internally

See Companions are part of their target.

Self-Referencing Values

${self.env.KEY} resolves to the resolved value of this package’s own earlier-declared KEY var. It is legal only in env values, never in entry-point args.

  • Declaration order: KEY must be declared strictly earlier in the same env array. A forward or self reference, or a reference to a key declared twice, is refused at publish time
  • Resolves to: KEY’s resolved value, not its unexpanded template
  • Surface: independent of KEY’s own visibility and of whether --self is on
  • Failure: a malformed template, a required path that does not exist on disk, or an unresolvable ${self.env.KEY} fails the whole composition with exit 65. This applies to any var of the package, including one not emitted on the surface in play
  • Commands: the failure applies to ocx env, ocx package env, ocx exec and ocx package exec on either surface

See self.env and Interpolation Tokens.

Integrations

Package metadata can declare vendor-namespaced integrations blocks, and composition carries them as attributed rows without interpreting them. Two packages that declare the same namespace produce two independent rows, and OCX never merges them.

See What composition does.

Row Shape

integrations is a fourth top-level array of the --format json envelope, beside items, binaries and entrypoints, and never nested inside items. The array is present, with attribution, even when composing a single package.

{
"items": [ … ],
"binaries": [ … ],
"entrypoints": [ … ],
"integrations": [
{
"namespace": "com.microsoft.vscode",
"package": "acme/mytool:1.0@sha256:aaaa…",
"payload": { "extensions": ["rust-lang.rust-analyzer"] }
}
]
}
  • namespace: the declared key
  • package: the canonical resolved identifier of the declaring package. The tag may be absent, and a digest-pinned identifier is legal
  • payload: that package’s block, interpolated against that package’s own ${self.installPath}, never the composing root’s
  • Filter: .integrations[] | select(.namespace=="…")

Ordering

Rows follow the admitted-set walk order of Composition Order: for each root, its admitted dependencies first in topological order, then the root itself. Roots keep the order the package set produced them in, and namespaces within one package’s contribution are ordered lexicographically.

  • Diamond: a dependency reached by two roots contributes once, at its first-seen position

Interface Surface Only

Integrations reach only the interface surface, at every depth: --self always composes "integrations": [], including a generated launcher’s forced private surface. An integrations block has no visibility field, unlike binaries and entrypoints, whose membership follows the two-axis visibility of each declared entry.

  • Private edge: a dependency reached only through a private edge contributes nothing on either surface

Patch Companions Contribute Too

A patch companion declaring integrations contributes them like any package. The row’s package field names the companion’s own identifier and never the base it was admitted for.

Absent from --shell and --ci

Neither --shell nor --ci output carries an integrations representation. Only --format json carries the array.

Composition Order

When several packages contribute to an environment, via ocx exec -g GROUP1,GROUP2 or ocx package exec PKG1 PKG2, path entries are prepended: the last package walked has its PATH entries placed first. In -g argument order, groups listed later win PATH lookup.

  • ocx exec order: first by group-selection order (the order of -g flags, after all expansion, deduplicated). Then alphabetical by binding name within each group

See Project toolchain: composition order rule.

List Variables

A list entry is appended and not prepended. Each contribution lands after the ambient value, so the last package or project stage to contribute lands at the very end.

[prepend-zone: vector reversed] [ambient value] [append-zone: vector order]
  • path: contributions land ahead of the ambient value, most recently applied first (move-to-front)
  • list: contributions land after the ambient value, in the order applied (move-to-back), which is what a last-wins consumer resolves to
  • Render: every fold, path or list, is a render and not accumulated state
  • Idempotence: re-running the fold with a value already present removes it from its old position and re-appends it at the back. A repeated ocx exec, a re-evaluated .envrc or a launcher re-entry therefore never grows a list variable
  • cmd.exe: ocx env --shell=cmd and ocx package env --shell=cmd skip every list-typed entry with a # ocx: note on stderr naming the key, and every other type still exports
  • cmd.exe scope: a text-export limitation only. The in-process environment that ocx exec and ocx package exec build for a child process on Windows is unaffected

See Rendering list variables.

Two entries for one key with different explicit separators fail the composition with exit 65. See Separator agreement, separator is required and the [env] value grammar.

Project Environment

ocx.toml can declare its own environment on top of what packages provide. [env] sets project-wide constants, [group.<name>.env] sets group-scoped ones, and the --env flag sets a one-off override.

See Project and group [env].

Precedence

Stage Source Notes
1 (lowest) Ambient inherited env The caller’s environment; minus what earlier OCX layers applied under --isolate, and skipped entirely under --clean
2 Package-composed env Composition order above — group-selection order, then alphabetical by binding name
3 Patch-companion overlay [patches] — each companion var on the surfaces of the package it matched; applied after all package env, before stages 4-6
4 Project [env] Constants replace; path entries prepend; list entries append
5 Group [group.<name>.env] In -g selection order — a group listed later wins
6 (highest) --env NAME or --env KEY[:TYPE[:SEP]]=VALUE Repeatable; constant (default) replaces, path prepends, list appends; a relative path value anchors to the current directory, not the project root stages 4-5 use. The bare NAME form carries the invoking process’s own value of NAME in at this stage, and contributes nothing when NAME is unset there
  • path across stages: every path application is idempotent with move-to-front semantics. So a stage 4, 5 or 6 path entry lands ahead of a stage 2 package path entry for the same key
  • list across stages: a stage 4, 5 or 6 list entry lands behind a stage 2 package list entry for the same key, in the same append zone. See List Variables
  • Shadowing: a project constant that shadows a package-declared constant of the same key logs at debug, never warn

Where --env lives

--env is a per-invocation override and not project configuration, so it is available on every command that composes an environment, on both command families. The ocx package commands read no ocx.toml, so stages 4 and 5 do not exist there.

Tier Commands Also available
Project toolchain ocx exec, ocx env, ocx direnv export -g/--group selects which groups’ [env] composes
Package (OCI) ocx package exec, ocx package env, ocx package test, ocx patch test --self selects the visibility surface
  • Export and execution agree: ocx env --env X composes stages 1 to 6 exactly as ocx exec --env X does, and ocx package env pairs with ocx package exec the same way
  • --clean, --isolate: control only stage 1, what the child inherits from the parent shell. Package env values come from ocx.lock and the resolved digests alone, with or without it
  • Forwarded under --clean: __OCX_ENV_STATE and OCX_BINARY_PIN always, written afresh from this invocation’s settings. They carry the resolution-affecting settings, including the root flags and the home
  • Project [env]: excluded from the lock’s declaration_hash, and it has no visibility axis because a project is never a dependency of anything
  • --self: package vocabulary, absent from the project commands