- integrations
- CMake
- Integrate
- Cross-build with foreign-platform content
Cross-build with foreign-platform content
You build on one CPU or operating system for another, for example linux/arm64 from an x86-64 laptop.
The target needs its own binaries, and copying them from another machine leaves two sets of versions to keep in sync.
This page provisions the content of the target platform from the same ocx.lock as your native build.
It then hands the content to CMake, either from a toolchain file or from CMakeLists.txt.
It assumes a project with a committed ocx.toml and ocx.lock, as in the tutorial.
A lock stores one digest per tool and platform, so no second lock is needed.
Request the platform
Section titled “Request the platform”Pass PLATFORM to ocx_project or ocx_package.
Use the same <os>/<arch> names as the keys in ocx.lock, such as linux/arm64, darwin/arm64 or windows/amd64.
PLATFORM takes one platform, and a list is a configure error.
To cover several targets, call the command once per platform with a different NAME.
OCX_DEFAULT_PLATFORM sets the platform for every call that has no PLATFORM.
An empty value means the host.
Foreign content is always downloaded at configure time, with or without PULL.
Foreign binaries cannot run on the host, so the lazy OCX_<NAME>_RUN commands do not exist.
Passing BINS together with PLATFORM is a configure error for the same reason.
Provision in a toolchain file
Section titled “Provision in a toolchain file”A toolchain file is the usual place to describe the target, so the provisioning call belongs there too.
CMake reads a toolchain file again for each compiler probe.
An ocx_project or ocx_package call with the same NAME and identical arguments does nothing on re-entry, so the call needs no guard.
A different call under the same NAME is a configure error.
The call registers ocx.toml and ocx.lock as configure dependencies, so the next build reruns the configure after you edit either one.
set(CMAKE_SYSTEM_NAME Linux)set(CMAKE_SYSTEM_PROCESSOR aarch64)
# CMake reads a toolchain file again for every compiler probe. An identical# ocx_project call is a no-op on re-entry, so no guard is needed.# In your own project, vendor ocx.cmake into cmake/ and use that directory here.list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/../..")include(ocx)ocx_project(NAME TARGET TOML "${CMAKE_CURRENT_LIST_DIR}/ocx.toml" PLATFORM linux/arm64)
list(APPEND CMAKE_FIND_ROOT_PATH ${OCX_TARGET_PATHS})
# Search the target root only: with the default BOTH a find_library() or# find_package() would fall back to a host copy that cannot link or run on# the target. Programs are the opposite: they run on the host.set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)OCX_TARGET_PATHS lists the content directories of the target platform.
For a package that ships a sysroot, headers or libraries, CMAKE_FIND_ROOT_PATH lets find_package and find_library search it.
Use CMAKE_SYSROOT instead when the package is the whole sysroot.
The four CMAKE_FIND_ROOT_PATH_MODE_* lines narrow the search.
Without them, the libraries, headers and packages of the target fall back to the copies of the build machine.
The result links into a binary that cannot run on the target.
Programs stay on the build machine, because they run there.
The project tier renders its links into .ocx/toolchain/ next to ocx.toml.
That directory ignores itself with its own .gitignore, so there is nothing to add to yours.
It is not the committed .ocx/ index snapshot of pin and freeze, which sits in the same .ocx/ directory under a registry name.
Read the content in your build
Section titled “Read the content in your build”A foreign call exports content, not commands.
OCX_<NAME>_PATHSlists the content directories.OCX_<NAME>_ENV_KEYSlists the environment keys the packages set.OCX_<NAME>_ENV_<KEY>holds the value of each key.
These are internal cache variables, so cmake -L and cmake-gui do not list them.
Print them with message(STATUS ...) while you set up the build.
For jq the path is the package content directory, and the binary sits directly in it, not in a bin directory.
This example copies the content into an install tree that you ship to the target.
# toolchain.cmake provisioned the arm64 content: OCX_TARGET_PATHS lists the# content directories, OCX_TARGET_ENV_KEYS the environment keys the packages set.foreach(dir IN LISTS OCX_TARGET_PATHS) install(DIRECTORY "${dir}/" DESTINATION payload USE_SOURCE_PERMISSIONS)endforeach()Run it
Section titled “Run it”The recording requests Windows content on a Unix host.
The first configure passes BINS together with PLATFORM and fails with PLATFORM is incompatible with BINS.
After the sed command drops BINS, the configure succeeds and prints the exported content path, which holds jq.exe.
cmake -S . -B build
sed -i.bak 's/ BINS jq//' CMakeLists.txt
cmake -S . -B buildPin a single package
Section titled “Pin a single package”ocx_package accepts PLATFORM as well, but it has no lock.
A floating tag such as :latest is then a configure error until you pin it with an index snapshot or an index digest.
The pin and freeze and image index digest pages show both.
Use OCX_ALLOW_FLOATING only once, to resolve the tag before you pin it.
Next steps
Section titled “Next steps”- Pin and freeze tag resolution to pin a foreign
ocx_package. - Reproduce the build in CI to run the cross build on every push.
ocx_projectandocx_packagelist the full signatures.