Build Neat

This guide covers source builds of Neat. For prebuilt package installation, see Neat Library.

build.sh is the supported build entry point. It handles dependency checks, optional deps sync, CMake configure/build, optional docs generation, install sanity checks, and packaging.

Build Environments

build.sh automatically detects the active environment:

• Modalix DevKit native environment
• Palette SDK environment (cross-compilation)

You can run the same build.sh commands in either environment.

Cross Compilation Prerequisites

Use the Palette SDK for cross-compilation. Follow Install the SDK to set it up on a supported Ubuntu, Windows/WSL, or macOS host, then open its shell:

sima-cli sdk neat

The SDK includes the toolchain and sima-cli. Core's build.sh prepares the matching Scheduler and LLiMa dependencies; see Local dependencies. In a paired SDK, ./build.sh --install also deploys matching artifacts to the DevKit. Native DevKit builds do not require the SDK.

Build Options

Supported build.sh options:

• --dev-only: Build only the core library and headers (default).
• --all: Build library + tests + tutorials + Python wheel; enables docs and deps.
• --python: Build Python bindings (pyneat) in addition to selected targets.
• --install-neat-internals, --install-deps: Download and install deps artifacts before build.
• --doc: Build docs only.
• --install: After build/package, install generated artifacts into the current environment. In paired Palette SDK mode, this also deploys and installs matching artifacts on the paired DevKit.
• --no-dist: Skip distribution packaging.
• --clean: Remove build/ before configuring.
• --no-doc: Skip docs build (even with --all).
• --no-node: Skip Node.js install (docs build may fail if Node is missing).
• --install-deps-only: Install system dependencies and dependency headers, then exit.

Compiler Cache

build.sh enables sccache automatically, and its cache remains available after --clean. Local builds use a user-local disk cache. Vulcan gives develop and main separate protected caches; a feature branch seeds an isolated writable cache from its closest protected base and keeps it until the branch is deleted.

See the Neat sccache Cheatsheet for local controls, cloud access rules, cache namespaces, statistics, verification, and troubleshooting.

Typical Builds

Core library only (default):

./build.sh

Full build (library, tests, tutorials, docs, wheel, packaging):

./build.sh --all

Core library + Python bindings:

./build.sh --dev-only --python

Docs only:

This command also works on macOS.

./build.sh --doc

The docs build generates the Insight API reference from the OpenAPI specification downloaded by autodoc at build/autodoc/insight/neat_insight/openapi.json. For local development, you can override that default with INSIGHT_OPENAPI_SPEC:

INSIGHT_OPENAPI_SPEC=../insight/neat_insight/openapi.json ./build.sh --doc

Relative override paths are resolved from the Core repository root and converted to absolute paths before the Docusaurus generator runs. If the selected file does not exist, the Insight API generation step is skipped and the path is reported.

Clean full build:

./build.sh --all --clean

Install dependencies without building core:

./build.sh --install-deps-only

Outputs

• Build tree: build/
• Docusaurus site output (when docs build runs): website/build/
• Install sanity-check prefix: a unique temporary directory (${TMPDIR:-/tmp}/sima-neat-install-test.XXXXXX) printed during the build; removed on success, kept on failure for inspection.
• Neat package artifacts (*.deb) are generated on Linux full builds unless --no-dist is used.
• Extras package (*extras.tar.gz) is generated on Linux full builds unless --no-dist is used.
• Python wheel (dist/*.whl) is generated when Python build is enabled.

The Python wheel packages the _pyneat_core extension produced by the main CMake build. Wheel creation does not configure or compile a second CMake tree, so the library, DEBs, extras archive, and wheel share one compilation.

Build Profiles & CMake Options

The framework's top-level CMakeLists.txt exposes a handful of options that control what gets built and how. The options below are the load-bearing ones.

Build profiles

The framework supports three named profiles:

Profile	Use case	What's compiled
Production	Customer-facing builds	All public Nodes, model-archive loading, Modalix backends, optimized
Developer	Framework engineers	Production set + debug Nodes + extended diagnostics + tests
Sandbox	Multi-tenant deployments	Production set + tightened model-archive security defaults

Pick via -DSIMA_NEAT_PROFILE=Production|Developer|Sandbox at configure time, or accept the default in CMakeLists.txt.

Common CMake options

Option	Default	Effect
SIMA_NEAT_BUILD_TESTS	ON (Developer)	Build the gtest suite. Disable for faster CI on production builds.
SIMA_NEAT_BUILD_TUTORIALS	OFF	Build the tutorial binaries.
SIMA_NEAT_BUILD_PYTHON	ON	Build the pyneat nanobind module.
SIMA_NEAT_BUILD_INTERNALS	OFF (public)	Build the internal reach-through tier (core/src/pipeline/internal/sima/).
SIMA_NEAT_ENABLE_TVM_FALLBACK	ON	Compile TVM-backed fallback kernels for ops the MLA can't handle.
SIMA_NEAT_ENABLE_RTSP	ON	Build the RTSP source/sink Nodes.
SIMA_NEAT_DEBUG_PLUGINS	OFF	Forward GStreamer plugin debug to stdout.
SIMA_NEAT_USE_SYSTEM_GSTREAMER	ON (host) / OFF (cross)	Link against the system's GStreamer instead of bundling.
SIMA_NEAT_WARN_AS_ERROR	OFF	Promote compile warnings to errors. Recommended for CI.

Toolchain knobs

For cross-compilation toward Modalix:

cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=cmake/modalix.cmake \
  -DSIMA_NEAT_PROFILE=Production

For host-side development:

cmake -B build -DSIMA_NEAT_PROFILE=Developer

To enumerate what your tree exposes:

cmake -L -B build       # list all cache variables
cmake -LA -B build      # include advanced

The top-level CMakeLists.txt is the source of truth for option names.

Core inherits firmware and the exact sysroot from the selected Scheduler package receipt; it does not declare firmware separately. The receipt must match Core’s platform and SDK channel. CI retains that policy with the build artifacts and uses it to select the exact DevKit without fallback. Before installing LLiMa, Core checks its published firmware, platform and SDK channel against Scheduler and verifies the selected DEBs against the same publication. LLiMa does not publish an exact sysroot receipt, so this check establishes declared firmware compatibility, not identical sysroot inventories. For local --llima PATH builds, provide the root LLiMa distribution containing the core/dev/cli DEBs, llima-package-manifest.json and metadata.json. Missing or conflicting evidence stops the build. Rebuild and publish Kernels → Runner → Scheduler, and matching LLiMa, before rebuilding Core.