---

name: bindings-and-packaging description: "Build, install, packaging, C/Rust/WASM/npm, and release-version workflows for ONNX Simplifier." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

bindings-and-packaging

Use this sub-skill when the task is about installing, building, linking, packaging, releasing, or diagnosing ONNX Simplifier bindings. It covers Python wheels/editable builds, direct CMake builds, the C ABI, Rust crates, WebAssembly, the web demo/npm package, version synchronization, and maintainer test selection.

Route first

• If the task asks how to call onnxsim.simplify, pass CLI flags, set input shapes, choose providers for simplification checks, or simplify an ONNX model, route to ../python-simplification/SKILL.md.
• If the task asks about custom rewrite semantics, FunctionProto rule authoring, ModelInfo, MACs/FLOPs/memory metrics, graph diff, metadata, or profiling, route to ../advanced-graph-control/SKILL.md.
• Stay here for package installation, native build options, C/Rust/WASM/npm binding mechanics, release/version checks, and build/test triage.

Non-negotiable build fact

The Python wheel/editable/source build driven by setup.py passes -DONNXSIM_BUILTIN_ORT=OFF. It builds the Python extension onnxsim_cpp2py_export, ONNX/onnx-optimizer/protobuf pieces needed by that extension, and compiles with NO_BUILTIN_ORT; it does not compile the vendored ONNX Runtime C++ source. onnxruntime is only an optional Python runtime dependency for constant folding and correctness checks. If a build is compiling ONNX Runtime C++, it is on the standalone C++/WASM/C API/Rust native library path where ONNXSIM_BUILTIN_ORT=ON, not the Python wheel path.

Primary references

• Build and binding recipes: references/build-and-bindings.md
• WASM, ORT-web, npm, web demo, WebNN, and DLPack boundaries: references/wasm-and-web.md
• Failure-mode triage: references/troubleshooting.md
• Safe version checker: scripts/check_version_sync.py

Choose the workflow

1. Released Python package: install the wheel when the user only needs the CLI/Python package.

   python -m pip install -U onnxsim
   python -m pip install -U "onnxsim[onnxruntime]"  # optional faster/checking runtime
   python -c "import onnxsim; print(onnxsim.__version__)"
   onnxsim --help
   onnxsim --list-default-optimizers
   

2. Local Python editable/source build: use when changing Python/C++ extension code or building from an sdist/checkout. Initialize submodules for a checkout, install build tools, and keep the build scoped to the Python extension.

   git submodule update --init --recursive
   python -m pip install -U pip setuptools wheel cmake ninja nanobind
   CMAKE_GENERATOR=Ninja python -m pip install -e . -v
   

   Optional knobs include MAX_JOBS=<n>, CMAKE_ARGS="...", DEBUG=1, COVERAGE=1, ONNX_OPT_USE_SYSTEM_PROTOBUF=1, ONNXSIM_RELEASE=<version>, and platform-specific compiler variables. Do not add ONNXSIM_BUILTIN_ORT=ON for a normal Python wheel investigation.

3. Standalone C++ executable or C API: use direct CMake. The C API requires built-in ORT because it provides the native constant-folding executor.

   git submodule update --init --recursive
   cmake -S . -B build -DONNXSIM_C_API=ON -DONNXSIM_BUILTIN_ORT=ON
   cmake --build build --target onnxsim_c
   

   To skip a full ONNX Runtime source compile on supported native platforms, add -DONNXSIM_PREBUILT_ORT=ON and optionally set ONNXSIM_ORT_VERSION, ONNXSIM_ORT_HOME, or ONNXSIM_ORT_URL.

4. Rust crates: build inside rust/ for in-tree development, choose one of the native-library modes for downstream consumers, and use check-only mode for docs or type-checking.

   cd rust
   ONNXSIM_NO_BUILD=1 cargo check --workspace
   ONNXSIM_PREBUILT_ORT=1 cargo build --release --workspace
   ONNXSIM_LIB_DIR=/path/to/libs cargo build --release
   

   ONNXSIM_LIB_DIR links a prebuilt onnxsim_c; ONNXSIM_SOURCE_DIR points a published crate at a checkout with submodules; ONNXSIM_NO_BUILD=1 skips the native build and cannot produce a runnable binary.

5. WASM/web/npm: only run these long builds when the user explicitly needs a WASM module, web demo, or npm package. The npm package uses the ORT-web variant.

   ./build_wasm.sh                 # default WASM, compiles built-in ORT
   ORT_WEB=ON ./build_wasm.sh      # no ORT C++ compile; delegates to onnxruntime-web
   ./scripts/stage_npm_package.sh build-wasm-node-OFF-ortweb
   (cd npm/onnxsim && npm install && npm test && npm pack)
   

Safe local checks for this sub-skill

Do not launch long native, Rust, npm, or WASM builds just to inspect a task. Start with deterministic checks:

python scripts/check_version_sync.py --help
python scripts/check_version_sync.py --repo-root /path/to/onnxsim-checkout

The checker compares the root VERSION, Rust workspace/crate dependency versions, and npm package version when present. It never writes files.

Maintainer test selection

• Version/release metadata: run the bundled checker or the repository's read-only version-sync check before a release. Mutating bump scripts are release-only; do not run them for diagnosis unless the user asked to bump.
• Python wheel path: wheel CI builds Linux/macOS wheels and Windows wheels by cross-compile, then runs pytest, onnxsim -h, and onnxsim --list-default-optimizers. PRs intentionally use a reduced Python matrix; release/push runs are broader.
• Rust path: ONNXSIM_NO_BUILD=1 cargo fmt/clippy/check is fast; native cargo build/test is long; the standalone-package test validates published crate behavior outside a source checkout.
• WASM/npm path: use the ORT-web build plus npm test && npm pack. Hosted demo previews and Netron embedding are heavier than npm package validation.
• Optional integration/regression paths: TVM, Halide, ModelOpt, QNN, model-regression, YOLO, RF-DETR, VOICEVOX, X2Paddle, coverage, sanitizer, and big-endian jobs are targeted or scheduled. Do not treat their dependencies as required for the minimum build/install environment.

Quick troubleshooting route

• Python build unexpectedly compiles ONNX Runtime: see references/troubleshooting.md.
• CMake/submodule/nanobind/protobuf errors: see references/troubleshooting.md.
• C API or Rust link failures: see references/troubleshooting.md.
• WASM, ORT-web, npm staging, or WebNN issues: see references/troubleshooting.md.
• Optional provider dependencies and skipped heavy tests: see references/troubleshooting.md.

Handoff checklist

• State which build path is in scope: Python package, standalone CMake, C API, Rust, WASM/web, npm, or release/version work.
• Preserve the Python-wheel built-in-ORT caveat exactly.
• Use concrete commands with prerequisites and expected validation outputs.
• Keep original long scripts as reference knowledge; use only the bundled safe checker as a runtime helper.
• When a fix needs API behavior rather than binding mechanics, route to the sibling sub-skill instead of duplicating semantics here.