Building the Software Framework

This documents discusses the various build options that can be used when configuring and compiling Basilisk. The build system makes use of the conan package manager which provides for cross platform manner support. As a result the Basilisk build instructions are platform agnostic.

This page is broken up into distinct manners of building Basilisk starting with the simplest method that should work for the majority of users. This is followed by increasingly more detailed discussions on the build system for users who want to customize.

One-Step Configuring and Building the Basilisk Framework

If you just installed the Basilisk source code, or changed any source file, you will want to recreate the Basilisk IDE project or makefile to compile it. This creates or updates the project file to included the latest Basilisk source code. From the Basilisk root directory, this is done simply using:

python3 conanfile.py

This one-line step will use conan to:

pull and compile any resource dependencies such a protobuffer, etc.
configure the Xcode (macOS) or Visual Studio (Windows) IDE project in the dist3 folder, or create the makefile for Linux systems
build the project.

By default the build is for Python3 with the support for C++ Module: vizInterface included to enable recording data for or live-streaming to Vizard.

The script accepts the following options to customize this process.

Options for One-Step Configure/Build Process
Option	Values	Default	Description
`vizInterface`	Boolean	True	Includes the Google Protobuffer library to package up Vizard data messages, and the Zero-MQ library to communicate with Vizard.
`opNav`	Boolean	False	Includes OpenCV library to create visual navigation modules that use OpenCV to process sensor images. If this option is selected, then the dependencies of `vizInterface` are also loaded as some components require the same libraries. Note that OpenCL related dependencies can take a while to compile, 10-20minutes is not unusual. However, once install they don’t need to be rebuilt unless `.conan` is deleted or the dependency changes.
`clean`		None	If flag is set, this deletes the distribution folder `dist3` and Basilisk Numba cache artifacts to create a fresh setup and build
`buildProject`	Boolean	True	If set to True, this option will compile the project right away after creating the IDE or make file
`buildType`	Release, Debug	Release	Sets the build type. This does not apply to the IDE project like Xcode and Visual Studio which control the build type through their interface.
`strictWarnings`	Boolean	False	Enables additional compiler diagnostics for Basilisk C and C++ sources. See Strict Compiler Warnings.
`generator`	see here	`XCode` (macOS), `Visual Studio 16 2019` (Windows), `None` (Linux)	If not set the `cmake` build generator is automatically selected to be `XCode` for macOS, `Visual Studio 16 2019` on Windows, and `None` for Linux which create a make file on this platform. It can also be set through this flag. If unsure what generators are supported on your platform, open a terminal window and type `cmake --help` to get a list of supported generator strings.
`autoKey`	String ‘s’ or ‘u’	Empty	This is used to automatically respond to the python packaging installation requests to install the package for the user (u) or system (s).
`allOptPkg`		None	If flag is set the Basilisk python package depenencies to build documentation are installed
`pathToExternalModules`	String	Empty	path to external modules folder, see Building Basilisk with External Modules
`mujoco`	Boolean	False	[BETA] Mujoco Support Includes the MuJoCo dependencies
`rustModules`	Boolean	False	[BETA] Rust Module Support Enables discovery and compilation of in-tree Rust modules. Requires Rust and Cargo. See [BETA] Making Rust Modules for the minimum supported Rust version and setup details.
`examples`	Boolean	True	Installs the optional Python dependencies used by Basilisk example scripts, such as `scipy` and `numba`. Disable this flag if you want a leaner clone-based install and do not need the example-only Python packages.
`recorderPropertyRollback`	Boolean	False	Version 2.8 changed the output format when querying non-numeric types in message recorders. By using this flag, the previuos behavior is recovered. Note that this build flag will disappear in the near future.

Thus, for example, to create a build with opNav modes enabled, but no C++ Module: vizInterface, and using a clean distribution folder, and that is built right away, you could use:

python3 conanfile.py --clean --opNav True --vizInterface False --buildProject True

The buildProject argument here is optional as its default value is True. Likewise, the examples argument is optional as its default value is True. To skip the optional example Python packages during the clone-based install, use:

python3 conanfile.py --examples False

Strict Compiler Warnings

Developers can enable additional compiler diagnostics with:

python3 conanfile.py --buildProject True --strictWarnings True

The option is disabled by default and does not change the warning policy of a normal Basilisk build. When enabled, Clang and GCC builds check additional cases involving numeric conversions, signedness, selected shadowed local declarations, format strings, implicit fallthrough, unused parameters, double promotion, and other potentially unsafe constructs. Intentionally unused interface parameters are marked explicitly, and intentional numeric conversions are made explicit in the source. Clang builds also diagnose implicit 64-bit to 32-bit conversions. MSVC builds use warning level /W4 and enable its size-conversion diagnostic. Warnings remain warnings; this option does not enable -Werror or otherwise make every warning a build failure.

For example, a clean MuJoCo-enabled build with the additional diagnostics is created with:

python3 conanfile.py --clean --mujoco True --strictWarnings True

The warning policy is defined in CMake so it is consistent across supported CMake generators, including Unix Makefiles, Ninja, and Xcode. SWIG and Protocol Buffer generated source, Conan-provided dependencies, imported model implementations, and other third-party targets are not part of the Basilisk warning baseline. Developers invoking CMake directly can enable the same policy with -DBSK_STRICT_WARNINGS=ON.

Warning

If you switch between building for release (default) and debug, you must re-run this command again. Otherwise you will not have the correct conan dependencies included for your build type. In the IDE like Xcode, for example, if you do a regular build you are building for debug, not for release. Thus, be mindful of how you are building the code.

Inspecting the Build Toolchain

Every Basilisk build records its configured optional features, C and C++ compilers, build configuration, CMake generator, and versions of the principal build tools in the installed Python package, including a wheel. Rust-enabled builds also record the Rust compiler and target, Cargo, and Corrosion. This information can be inspected when diagnosing a binary or build issue.

For a concise, human-readable summary, use printBuildInfo():

from Basilisk import printBuildInfo

printBuildInfo()

For a Rust-enabled build, this produces output similar to:

Basilisk Build Information
  Version:        2.12.0 (extension ABI 2)
  Target:         macOS arm64, 64-bit
  Build:          Release, Unix Makefiles
  Features:       vizInterface=on, opNav=off, mujoco=off, rustModules=on
  C compiler:     AppleClang 21.0.0.21000101 (cc)
  C++ compiler:   AppleClang 21.0.0.21000101 (c++)
  Rust compiler:  rustc 1.97.1 (rustc)
  Rust target:    aarch64-apple-darwin
  C standard:     C17
  C++ standard:   C++17
  C++ ABI:        libc++ (210106, ABI 1), Itanium ABI
  C++ runtime:    system, exceptions, RTTI
  Python API:     0x03090000
  Eigen:          3.4.0, 16-byte max alignment, NEON
  SWIG runtime:   5
  Conan profile:  Release, C++17, libc++

Build Tools
  CMake:          4.2.0
  Conan:          2.23.0
  SWIG:           4.4.1
  Python:         3.14.6
  Cargo:          1.97.1
  Corrosion:      0.6.1

For programmatic inspection or custom formatting, use getBuildInfo(). It returns a copy of a versioned nested dictionary with four principal sections:

from Basilisk import getBuildInfo, hasBuildFeature

buildInfo = getBuildInfo()
mujocoEnabled = buildInfo["features"]["mujoco"]
opNavEnabled = hasBuildFeature("opNav")
rustModulesEnabled = hasBuildFeature("rustModules")
extensionAbiVersion = buildInfo["artifact"]["extensionAbiVersion"]
standardLibrary = buildInfo["abi"]["cxx"]["standardLibrary"]["family"]
compilerVersion = buildInfo["diagnostics"]["compilers"]["cxx"]["version"]
rustCompilerVersion = buildInfo["diagnostics"]["compilers"]["rust"]["version"]

The top-level schemaVersion identifies the format of the complete dictionary, including the nested abi section.

artifact identifies the Basilisk version, source revision when available, and extension ABI epoch. The epoch is incremented when Basilisk intentionally changes the C/C++ object contract exposed to SDK extensions. It does not promise compatibility between different Basilisk versions; the SDK’s exact-version check remains required unless a future compatibility policy explicitly relaxes it.

features records whether vizInterface, opNav, mujoco, and rustModules were enabled when CMake configured the core artifact. hasBuildFeature() answers whether the installed Basilisk environment provides a capability: it combines those core values with capabilities supplied by installed optional Basilisk distributions such as bsk-opnav. Optional distributions declare their capabilities through package entry-point metadata and must have the same version as the core artifact. A mismatched provider raises RuntimeError instead of exposing an incompatible compiled extension. This distinction lets getBuildInfo() retain the core artifact’s provenance while feature guards continue to work when Basilisk is distributed across multiple wheels. Feature names are case-sensitive, and an unknown name raises KeyError. These values describe compiled Basilisk capabilities; they do not report the availability of external applications such as Vizard.

abi is captured by C and C++ translation units compiled with the selected Basilisk build configuration. It records the actual target architecture, endianness, C and C++ language modes, compiler ABI, standard-library ABI and debug modes, runtime linkage, exceptions, RTTI, Python ABI, SWIG runtime epoch, and Eigen alignment and vectorization settings. It also contains size, alignment, and field-offset canaries for important C, C++, messaging, and Eigen types. These values are suitable inputs to a future BSK-SDK compatibility policy. Layout canaries detect common binary mismatches but do not prove semantic compatibility.

The public architecture/utilities/bskAbiDescriptor.h header is the single source of truth for the extension ABI version, canary types, and compiler-side extraction rules. It is included by the existing BSK-SDK architecture header synchronization, allowing Basilisk and an SDK extension to compile the same contract rather than maintaining parallel implementations.

diagnostics contains values observed by CMake, requested Conan settings, compiler details, and build-tool versions. Rust compiler, Cargo, and Corrosion fields are empty when Rust modules are disabled. These diagnostics remain useful when reproducing a build, but they are not all binary-compatibility requirements. For example, CMake and Conan versions should not be compared as part of an SDK compatibility decision. For Xcode and Visual Studio, diagnostics["build"] describes the multi-config generator while abi["build"]["configuration"] records the configuration that actually compiled the installed descriptor.

The standard-library pprint module provides an indented view when all recorded fields should be displayed:

from pprint import pprint
from Basilisk import getBuildInfo

pprint(getBuildInfo(), sort_dicts=False, width=100)

Absolute build paths and timestamps are intentionally omitted from this metadata. Source revision is empty and dirty state is reported as None when the source was built without Git metadata. Source revision and dirty state are captured when CMake configures the package metadata. Local incremental module-only builds refresh the compiled ABI descriptor, but they do not recapture Git provenance. Reconfigure or do a clean package build before relying on these fields for release provenance.

Doing Incremental Builds

If you are developing new Basilisk capabilities you will be looking to do incremental builds. Note that running python conanfile.py will delete the auto-created messaging related files and their compiled products. Compiling the messaging related files is a large component of the Basilisk build time. Thus, running this command is required if you make changes to the message file definitions, or add a new message file. However, it is not the preferred manner to compile Basilisk if you just need to do an incremental build.

Rather, run python conanfile.py --buildProject False to create the IDE file for your platform such as Xcode projeect file on macOS, MS Visual Studio project file on Windows, etc. Next, open the project file in your IDE and compile Basilisk there. The initial build is a clean build and will take a similar amount of time to compile the messaging related files. However, after making changes to a particular module, only this Basilisk module will need to be compiled and the compile times are drastically reduced.

Every loadable BSK module target depends on ABI metadata generation, so an incremental module-only build refreshes the compiled descriptor for the selected configuration. This refreshes the ABI details under getBuildInfo()["abi"]; the Git provenance fields under getBuildInfo()["artifact"] remain configure-time package metadata. Internal libraries consume the same ABI settings but do not carry this dependency because multi-configuration generators share some of their generated sources. Do not mix Debug and Release module binaries in one Basilisk package; switching configurations requires rebuilding the complete package.

Speeding Up Builds with `sccache`

sccache is a compiler cache that caches individual C++ object files by content hash. When source files have not changed, sccache returns the cached object instead of invoking the compiler, which can dramatically reduce clean-build times.

Install sccache with your system package manager, for example on macOS:

brew install sccache

Then set the following environment variables before building:

export CMAKE_C_COMPILER_LAUNCHER=sccache
export CMAKE_CXX_COMPILER_LAUNCHER=sccache

With these set, any build invocation (python3 conanfile.py, pip install -e ., etc.) will automatically use sccache. A warm cache reduces a full rebuild to only the linking step plus any files that actually changed.

To inspect cache statistics after a build:

sccache --show-stats

Note

sccache is also enabled automatically in CI via CMAKE_C/CXX_COMPILER_LAUNCHER environment variables set by the GitHub Actions build workflow.

Running Project Tests

The project employs two testing frameworks, specifically Pytest for python executed tests and Google Test for C/C++ executed tests.

To run all tests execute the following from the project root directory

python run_all_test.py

To run only the python test use the following commands.

cd src
pytest

To run only the C/C++ tests use

cd dist3
ctest

or on macOS ctest -C <Release or Debug>.