rules_ocx

Public API of rules_ocx.

Most consumers only need the ocx module extension (@rules_ocx//ocx:extensions.bzl). The repository rules are re-exported here for power users composing their own extensions on top of the same CLI-backed provisioning.

ocx_platform_constraints

load("@rules_ocx//ocx:defs.bzl", "ocx_platform_constraints")

ocx_platform_constraints(platform)

Bazel constraint labels for the os/arch prefix of an ocx platform key.

‘linux/arm64+libc.musl’ -> [‘@platforms//os:linux’, ‘@platforms//cpu:aarch64’]. For toolchain authors composing exec_compatible_with; also the hub’s source of config_setting constraint_values. Fails on an unmappable os/arch.

PARAMETERS

Name	Description	Default Value
platform	an ocx platform key (‘os/arch[/variant][+feature,…]’).	none

RETURNS

[os_constraint_label, cpu_constraint_label].

ocx_download

load("@rules_ocx//ocx:defs.bzl", "ocx_download")

ocx_download(name, dist_manifest, repo_mapping, triple, version)

Downloads a pinned ocx CLI release for the host platform.

The release row (URL + sha256) comes from the vendored dist.json snapshot of https://setup.ocx.sh/dist.json. Corporate mirrors: set OCX_INSTALL_DIST_URL to fetch a mirrored manifest instead, and/or OCX_INSTALL_MIRROR_URL to rewrite the artifact download to <mirror>/<tag>/<filename>. The manifest sha256 is enforced either way.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
dist_manifest	Release manifest snapshot (dist.json schema 1).	Label	optional	"@rules_ocx//dist:dist.json"
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).	Dictionary: String -> String	optional
triple	Escape hatch: exact release target triple, e.g. ‘x86_64-unknown-linux-gnu’ to prefer the glibc build. Defaults to host detection (Linux maps to musl).	String	optional	""
version	Exact ocx version to download, e.g. ‘0.3.10’.	String	required

ocx_package_hub

load("@rules_ocx//ocx:defs.bzl", "ocx_package_hub")

ocx_package_hub(name, bins, platform_reals, platform_repos, repo_mapping)

Multi-platform hub for an ocx.package() with platforms.

//:content (or, with bins, each named launcher) select()s the per-platform package repo matching the target platform — combine with a platform transition to fetch foreign-platform tools (e.g. for container images).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
bins	Lazy mode: launcher names to alias instead of //:content.	List of strings	optional	[]
platform_reals	repo slug -> real ocx platform, the source of each config_setting’s Bazel constraint_values.	Dictionary: String -> String	required
platform_repos	repo slug -> apparent name of the per-platform package repo.	Dictionary: String -> String	required
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).	Dictionary: String -> String	optional

ocx_package_repo

load("@rules_ocx//ocx:defs.bzl", "ocx_package_repo")

ocx_package_repo(name, bins, index, isolated_home, ocx, package, pins, platform, repo_mapping,
                 resolved_platform)

Provisions a single OCX package from an OCI registry.

//:content is the package tree; every executable reachable through the package environment becomes a runnable target //:<name> (host-platform repos only). For reproducibility, commit an index snapshot and reference it via index (tags then resolve frozen from the snapshot), or pin per-platform manifest digests via pins — plain floating tags resolve at fetch time and log the resolved digest.

With bins, provisioning is lazy: nothing is installed at fetch time, and each named executable becomes a launcher re-entering ocx package exec — content materializes on first execution and never becomes a Bazel action input (//:content is not available in lazy mode).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
bins	Lazy provisioning: names of the executables to expose (not validated at fetch time). When set, nothing is installed during the fetch — each name becomes a launcher re-entering ocx package exec, keyed on the digest-pinned reference. Requires a digest-pinned identity (pins or ‘@sha256:’); incompatible with isolated_home and index.	List of strings	optional	[]
index	Committed ocx index snapshot directory (created with ocx --index <dir> index update <package>). When set, tag resolution is frozen to the snapshot (--index --frozen): floating tags become reproducible until the snapshot is refreshed.	Label	optional	None
isolated_home	Keep the ocx store inside this repository instead of the shared user OCX_HOME.	Boolean	optional	False
ocx	The pinned ocx CLI binary.	Label	optional	"@ocx_tool//:ocx"
package	Fully-qualified identifier: ‘registry/repo[:tag][@sha256:…]’.	String	required
pins	ocx platform key -> ‘sha256:…’ manifest digest overriding the digest of package for that platform.	Dictionary: String -> String	optional	{}
platform	ocx platform key (‘linux/amd64’, …) to provision for; empty = host.	String	optional	""
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).	Dictionary: String -> String	optional
resolved_platform	Real ocx platform sent to -p — lets a declared platform be aliased to a different real one (variant/feature build). Empty = derive from platform. Runnable-target gating compares its os/arch prefix to the host; pins still key on platform.	String	optional	""

ocx_project_repo

load("@rules_ocx//ocx:defs.bzl", "ocx_project_repo")

ocx_project_repo(name, bins, groups, isolated_home, ocx, ocx_lock, ocx_toml, platform, repo_mapping)

Provisions the toolchain declared in a workspace ocx.toml/ocx.lock.

Fails when the lockfile is stale or missing (fix with ocx lock). Every executable reachable through the composed environment’s path entries becomes a runnable target //:<name>; the raw environment is loadable from //:env.bzl (OCX_ENV, OCX_HOME).

With bins, provisioning is lazy: nothing is pulled at fetch time, and each named executable becomes a launcher that re-enters ocx run — content materializes on first execution and never becomes a Bazel action input, so fully remote-cached builds download no tool content at all.

groups scopes both the pull and the composed environment. Omitted, ocx’s defaults apply: every group is pulled, but only the default [tools] table is composed into launchers — name groups explicitly (or use the reserved all) to expose their executables.

platform composes a foreign platform’s environment from the same ocx.lock: that platform’s leaves are pulled into the store and env.bzl holds their absolute store paths (sysroots, target libraries, container image content). Foreign repos expose no runnable launchers — the binaries do not run on this host.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
bins	Lazy provisioning: names of the executables to expose (not validated at fetch time). When set, nothing is pulled during the fetch — each name becomes a launcher re-entering ocx run, and actions key on the lockfile (a runfile) instead of tool content. Incompatible with isolated_home.	List of strings	optional	[]
groups	ocx.toml groups to provision (comma-joined into -g for ocx pull, ocx env, and lazy ocx run). Reserved names: ‘default’ = the top-level [tools] table, ‘all’ = default + every declared group.	List of strings	optional	[]
isolated_home	Keep the ocx store inside this repository instead of the shared user OCX_HOME.	Boolean	optional	False
ocx	The pinned ocx CLI binary.	Label	optional	"@ocx_tool//:ocx"
ocx_lock	The ocx.lock next to ocx_toml; watched so lock changes refetch.	Label	required
ocx_toml	The project ocx.toml declaring the toolchain.	Label	required
platform	ocx platform key (‘linux/arm64’, …) to compose for; empty = host. A foreign platform pulls that platform’s leaves from the same ocx.lock and exposes env.bzl only (no runnable launchers). Incompatible with bins — lazy launchers already resolve the executing host at run time.	String	optional	""
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).	Dictionary: String -> String	optional

This site is open source. Improve this page.