Linking onnx-light in C++#

The installed CMake package exports small targets under the onnx_light:: namespace. Public dependencies are propagated, so a consumer links only the highest-level feature it needs. See How the C++ libraries are split for the dependency graph and C++ onnx-light examples for complete projects.

Install and consume the package#

Build a static, pure C++ installation:

cmake -S . -B build-install \
      -DCMAKE_BUILD_TYPE=Release \
      -DONNX_LIGHT_BUILD_PYTHON=OFF \
      -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build-install --parallel
cmake --install build-install

A downstream project can then select one or more exported targets:

find_package(onnx_light CONFIG REQUIRED)

add_executable(my_reader main.cc)
target_link_libraries(my_reader PRIVATE onnx_light::lib_onnx_proto)

Common choices are:

onnx_light::lib_onnx_proto for model parsing and serialization;
onnx_light::lib_onnx_lib for schemas, checking, inlining, standard shape inference, and version conversion;
onnx_light::lib_onnx_shape for the standalone shape and peak-memory dispatch;
onnx_light::lib_onnx_patterns for standard graph rewrites;
onnx_light::lib_onnx_kernels for the reference runtime;
onnx_light::lib_onnx_backend_test for backend-test cases;
onnx_light::lib_onnx_gradient for gradient generation.

lib_onnx_backend_test propagates lib_onnx_kernels. The shape, pattern, kernel, and gradient targets propagate lib_onnx_core and lib_onnx_proto. Consumers do not need to repeat these dependencies.

For a non-standard installation prefix, set -DCMAKE_PREFIX_PATH=<installation-prefix> when configuring the consumer.

Configure-time options#

Option	Default	Effect
`ONNX_LIGHT_BUILD_PYTHON`	`ON`	Builds the nanobind modules and shared C++ libraries. `OFF` builds static libraries for pure C++ consumers.
`ONNX_LIGHT_PYTHON_STABLE_ABI`	`ON`	Builds the Python extensions with CPython’s stable ABI. Disable only for a coordinated native-ABI build of all nanobind consumers.
`ONNX_LIGHT_BUILD_KERNELS`	`ON`	Builds kernels, backend tests, gradients, and their Python modules. `OFF` produces the reduced proto/schema/shape/pattern package.
`ONNX_LIGHT_INSTALL`	`ON`	Installs headers, libraries, and CMake package files.
`ONNX_LIGHT_PROVIDE_ONNX_TARGETS`	`OFF`	Adds in-tree compatibility targets named `onnx`, `onnx_proto`, `onnx::onnx`, and `onnx::onnx_proto`.
`ONNX_LIGHT_BUILD_TESTS`	`OFF`	Builds C++ tests. Reduced tests remain available when kernels are off.
`ONNX_LIGHT_BUILD_BENCHMARKS`	`OFF`	Builds C++ benchmarks.
`ONNX_LIGHT_BUILD_FUZZERS`	`OFF`	Builds Clang/libFuzzer harnesses.
`ONNX_ML`	`ON`	Enables the `ai.onnx.ml` operator domain.
`ONNX_LIGHT_WERROR`	`ON`	Treats warnings from onnx-light targets as errors.
`ONNX_HARDENING`	`OFF`	Enables supported OpenSSF compiler and linker hardening flags.

Keep ONNX_LIGHT_PYTHON_STABLE_ABI enabled for published wheels. This option requests the stable ABI, but nanobind may use the native ABI when the requested mode is unavailable, notably on unsupported or free-threaded Python builds. Extensions that exchange onnx-light C++ objects must therefore match the effective python_stable_abi value reported by onnx_light.get_cpp_build_info(), rather than relying on the CMake option alone. Matching the effective ABI mode is necessary but not sufficient: consumers must link the exact shared onnx-light libraries loaded by Python, because a separately built or statically linked copy owns a different type and registry universe. Wheel tags are controlled independently by the packaging frontend, so a CPython-specific tag does not by itself mean that the extensions were compiled without the stable ABI.

The nanobind FAQ describes the complete cross-extension ABI compatibility contract and the related type-visibility requirements. Call onnx_light.get_cpp_build_info() before building a downstream extension to obtain nanobind_version, nanobind_platform_abi, python_stable_abi, compiler_id, compiler_version and cxx_standard together with the exact headers and runtime-library paths. Downstream builds can compare these values with their own configuration and reject an incompatible toolchain or ABI mode before a cross-module conversion fails at runtime.

onnx_light.get_cpp_build_info() → dict[str, str]#

Returns ABI metadata, headers and libraries used by the Python runtime.

The libraries are looked up next to the loaded _onnxpyprotoop extension, not in the source tree, so the result is correct for editable installs as well. Linking an extension to another build or installed copy of lib_onnx_core would create a second process-wide kernel registry.

Returns:: A dictionary with the nanobind version and platform ABI tag, compiler identity and version, C++ standard, stable-ABI mode, include_dir, library_dir and one <component>_library entry per runtime library built as a shared library. Python builds use shared core and proto libraries on every platform so extensions observe one runtime identity. On Windows, the matching <component>_import_library is added when the build tree is available.

The following example displays the ABI metadata and the exact headers and libraries selected by the imported package:

<<<

from pprint import pprint

from onnx_light import get_cpp_build_info

pprint(get_cpp_build_info())

>>>

    {'compiler_id': 'GNU',
     'compiler_version': '13.3.0',
     'core_library': '/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/onnx_light/onnx_py/liblib_onnx_core.so',
     'cxx_standard': '20',
     'include_dir': '/home/runner/work/xadupre.github.io/xadupre.github.io/onnx-light/onnx_light',
     'library_dir': '/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/onnx_light/onnx_py',
     'nanobind_platform_abi': 'nanobind_system_libstdcpp_gxx_abi_1xxx_use_cxx11_abi_1',
     'nanobind_version': '3.1.0',
     'proto_library': '/opt/hostedtoolcache/Python/3.12.14/x64/lib/python3.12/site-packages/onnx_light/onnx_py/liblib_onnx_proto.so',
     'python_stable_abi': 'OFF'}

Reduced build without runtime kernels#

ONNX_LIGHT_BUILD_KERNELS=OFF omits lib_onnx_kernels, lib_onnx_backend_test, lib_onnx_gradient, and their Python modules. The remaining Python modules and reduced C++ tests are supported:

cmake -S . -B build-reduced \
      -DONNX_LIGHT_BUILD_KERNELS=OFF \
      -DONNX_LIGHT_BUILD_PYTHON=OFF
cmake --build build-reduced --parallel

The exported package still contains lib_onnx_proto, lib_onnx_core, lib_onnx_manipulations, lib_onnx_lib, lib_onnx_op, lib_onnx_shape, and lib_onnx_patterns.

Drop-in upstream ONNX targets#

An installed package also provides an onnx compatibility package:

find_package(onnx CONFIG REQUIRED)
target_link_libraries(my_target PRIVATE onnx::onnx)

onnx::onnx aggregates the proto, schema, manipulation, and shape targets; onnx::onnx_proto provides only proto-compatible messages. For add_subdirectory or FetchContent consumers, set ONNX_LIGHT_PROVIDE_ONNX_TARGETS=ON to create the equivalent compatibility targets in the build tree.

Registering graph patterns#

The optimizer interface is in lib_onnx_core; standard ONNX rewrites are in lib_onnx_patterns and are registered explicitly:

target_link_libraries(my_target PRIVATE onnx_light::lib_onnx_patterns)

#include "onnx_core/builder/graph_graph.h"
#include "onnx_extensions/patterns/dispatch_table.h"

onnx_light::onnx_patterns::RegisterPatterns();
onnx_light::core::builder::GraphGraph optimizer(builder);
optimizer.Optimize();

Applications using only custom patterns may link onnx_light::lib_onnx_core and pass their pattern instances directly to GraphGraph.

Registering runtime kernels#

Link onnx_light::lib_onnx_kernels and register the built-in dispatch table before creating a runtime session:

#include "onnx_extensions/kernels/kernel_dispatch_table.h"

onnx_light::onnx_kernels::RegisterKernelFunctions();

See Runtime for session creation, execution pools, prepared execution, tuning, and profiling.

Using the source tree directly#

For monorepos, use the non-namespaced in-tree targets:

set(ONNX_LIGHT_BUILD_PYTHON OFF CACHE BOOL "" FORCE)
add_subdirectory(path/to/onnx-light)
target_link_libraries(my_target PRIVATE lib_onnx_lib)

The examples under examples/ use both installed and in-tree forms and are kept as executable linking tests.