- integrations
- CMake
- Everyday
- Pin an image index digest
Pin an image index digest
A configure stopped on a floating tag, and you want no .ocx/ snapshot directory in the repository.
A digest fixes what the tag means, so the same bytes come back on every machine.
This page pins the digest of the image index, which covers every platform with one value.
Read the index digest
Section titled “Read the index digest”Run ocx package inspect on the tag.
The first line of the output is the reference with its image index digest, and the tree below it lists the leaf manifests.
$ ocx package inspect ocx.sh/jqlang/jq:1.8.2ocx.sh/jqlang/jq:1.8.2@sha256:c295300441831e002c0ba54df8e6126cdd4064c63be2464bdc6b68d0012beec6└── candidates ├── darwin/amd64 · sha256:f750c91d28769d12298ba9a4c10340152fcbdd48c48102bf275c21d736cc72a2 · 451 B ├── linux/amd64 · sha256:913ff41f5e643a73c17a2e560e349d8eea255f50b293156e58da15b957baacae · 451 B └── ...With ocx --format json package inspect <ref>, the same digest is the pinned_digest field of each package.
Copy the index digest from the first line, and not a digest from the candidates below it.
After an ocx index update into a snapshot, the index digest is also the file name under .ocx/ocx.sh/p/jqlang/jq/o/sha256/.
Write it into PACKAGE
Section titled “Write it into PACKAGE”Append the index digest to the reference as @sha256:<index digest>.
Keep the tag in front of it, so a reader sees which version the digest stands for.
Nothing downloads until the first build-time execution.
ocx_package( NAME jq_pinned PACKAGE ocx.sh/jqlang/jq:1.8.2@sha256:c295300441831e002c0ba54df8e6126cdd4064c63be2464bdc6b68d0012beec6 BINS jq NO_ROOT)ocx selects the leaf manifest for the platform of the call, which is PLATFORM when set and the host otherwise.
A project’s ocx.lock records the leaf digests per platform under each tool, so an ocx_project build needs no pin of this kind.
Why the index digest
Section titled “Why the index digest”The index digest fixes the whole tag.
ocx still matches the full platform, including +features such as libc.musl, and verifies the leaf against the index.
A digest of a single leaf bypasses that selection.
ocx never checks that the leaf fits the platform, so a wrong digest installs the wrong binary silently.
One index digest also replaces a list of per-platform digests that you would otherwise keep in step by hand.
Next steps
Section titled “Next steps”- Pin and freeze tag resolution covers the index snapshot and the frozen configure.
- Add or change a pinned tool covers
ocx_project, whoseocx.lockrecords these digests for you. - Move from 0.3 to 0.4 shows the change from the removed
PINSkeyword. ocx_packagelists every keyword.