Advanced: Directly Building the Software Framework Using Conan

Warning

This method of compiling Basilisk is not typically required and should only be attempted by advanced users familiar with both conan and cmake. See Building the Software Framework for documentation on the regular build process.

Configuring and Building with conan Commands

Calling conanfile.py with Python dispatches one Conan command that installs missing dependencies, generates the build files, and calls the Basilisk recipe’s build() method. This section outlines the equivalent direct Conan command for advanced users.

Note

All commands are called from the Basilisk root directory.

Installing Dependencies and Building Basilisk

The command, in its minimal form, is:

conan build . --build=missing -s compiler.cppstd=17 -s:b compiler.cppstd=17

This command creates the dist3 distribution folder when needed, resolves the required third-party resources, compiles dependencies whose binaries are missing, generates the CMake files, and builds Basilisk. All build files are stored in dist3. It does not install or modify packages in the active Python environment. Install the requirements and create the editable Basilisk installation separately, as described in the platform-specific installation instructions. Applying C++17 to both the host and build profiles lets Conan match cached build tools directly instead of searching compatible configurations or querying a remote for an avoidable profile mismatch.

For the direct equivalent of Preparing for Offline Builds, replace --build=missing with --build=never, disable remotes, and enable Basilisk’s offline CMake and Cargo behavior through its Conan configuration value:

conan build . --build=never --no-remote \
    -c user.basilisk:offline=True \
    -s compiler.cppstd=17 -s:b compiler.cppstd=17

The matching configuration must first have been built online so its Conan packages, GoogleTest or Corrosion sources, and Rust crates are already cached.

There are several options that can be provided to this conan build command as shown in the following table. Note that the option names for groupings of Basilisk modules are the same as with the one-step build above. The &: prefix scopes each option to the Basilisk consumer recipe. Keep the option expression in double quotes because & is a shell control character.

Options for conan build

Option	Values	Default	Description
-o "&:vizInterface=<value>"	Boolean	True	Include C++ Module: vizInterface in the configuration and build
-o "&:opNav=<value>"	Boolean	False	Include the OpenCV library dependent Basilisk modules.
-o "&:clean=<value>"	Boolean	False	Delete the configured build folder and Basilisk Numba cache artifacts before configuring to yield a fresh build. The build folder must either be empty or contain Basilisk ownership metadata, and its resolved path cannot traverse a symbolic link or junction. Existing CMake builds are accepted only when their cache identifies the selected Basilisk source tree.
-o "&:buildFolder=<path>"	Directory path	dist3	Select the build folder. Relative paths are resolved from the Basilisk source directory.
-o "&:buildProject=<value>"	Boolean	True	Will build the project executable after the configuration step
-o "&:buildTesting=<value>"	Boolean	True	Builds the native GoogleTest executables and registers them with CTest
-o "&:exportCompileCommands=<value>"	Boolean	True	Exports compile_commands.json with Ninja or Makefile generators for clangd and other language servers. Xcode and Visual Studio do not support export. Setting this option to False also removes an existing database from the selected build directory. See Configuring clangd for generator and editor configuration.
-s build_type	Release, Debug	Release	Specifies the build type
-o "&:strictWarnings=<value>"	Boolean	False	Enables the additional Basilisk compiler diagnostics described in Strict Compiler Warnings
-o "&:generator=<value>"	see here	Automatically selected	Used to specify a specific cmake generator. See discussion in Table Options for One-Step Configure/Build Process.

Thus, using the same build example as in the one-step section, 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:

conan build . --build=missing -s compiler.cppstd=17 -s:b compiler.cppstd=17 \
    -o "&:clean=True" -o "&:buildProject=True" -o "&:opNav=True" -o "&:vizInterface=False"

Note how much more verbose this is, but it gives you full control if you want to store the compiled binaries and cmake files in directories other than dist3/conan.

Configuring clangd

Compilation database export is supported only by CMake’s Ninja and Makefile generators. Xcode and Visual Studio do not export a database, even when exportCompileCommands=True. For a new build directory, --buildProject False defaults to Xcode on macOS and Visual Studio on Windows. Windows command-line builds also fall back to Visual Studio when Ninja is unavailable.

To configure a new Ninja build without compiling Basilisk, install Ninja and ensure it is available on PATH, then run from the Basilisk repository root:

python3 conanfile.py --generator Ninja --buildProject False

If the existing build directory uses another generator, add --clean to remove its previous build artifacts before configuring Ninja. See Options for One-Step Configure/Build Process for generator selection details and the CMake export documentation for supported generators.

With exportCompileCommands=True and a supported generator, CMake writes compile_commands.json into the configured build directory, which is dist3 at the Basilisk repository root by default. Clangd does not automatically search dist3, so it must be configured to find the generated database.

Setting -o "&:exportCompileCommands=False" removes an existing compile_commands.json from the selected build directory during conan install or conan build generation, including when using a custom buildFolder or Conan output folder. This cleanup applies to every generator. Separately copied databases must be removed manually.

Create or update a .clangd file at the Basilisk repository root with the following setting:

CompileFlags:
  CompilationDatabase: dist3

The path is relative to the .clangd file. If that file already has a CompileFlags section, add CompilationDatabase to that section.

For a custom Conan buildFolder, set CompilationDatabase to the directory containing the generated compile_commands.json, using either a path relative to .clangd or an absolute path. For example, -o "&:buildFolder=/absolute/path/to/bsk-build" requires CompilationDatabase: /absolute/path/to/bsk-build.

Alternatively, add --compile-commands-dir=/absolute/path/to/basilisk/dist3 to the arguments your editor passes to clangd. Replace the example path with the absolute path to your actual build directory, including when using a custom buildFolder. Both settings name the directory containing the database, rather than the JSON file itself. See the clangd configuration documentation for details.

Running cmake Directly

Advanced users can still run conan install . --build=missing separately when they intentionally want to prepare dependencies and toolchain files without calling the recipe’s build() method. They must then configure CMake with the generated Conan toolchain before running CMake directly from the dist3 distribution folder. This optional split workflow is not used by python conanfile.py.

The following table summarizes the optional Basilisk related flags that can be provided to cmake. If they are not used, then the shown default behaviors are used.

cmake Basilisk Build Flags

cmake Flag	Default	Description
BUILD_VIZINTERFACE	ON	will create C++ Module: vizInterface
BUILD_OPNAV	OFF	will create the OpenCL dependent optical navigation related modules
BUILD_TESTING	ON	fetches GoogleTest and builds the native C++ test executables
BSK_STRICT_WARNINGS	OFF	enables additional compiler diagnostics for Basilisk C and C++ sources
BSK_OFFLINE_BUILD	OFF	prevents GoogleTest, Corrosion, and Cargo dependency resolution from accessing the network; the required sources and crates must already be cached
BSK_FETCHCONTENT_CACHE_DIR	<Basilisk root>/.bsk-cache/fetchcontent	selects the persistent GoogleTest and Corrosion source cache used by online and offline builds

macOS Example

$ cmake ../src -G Xcode -DBUILD_OPNAV=ON

Linux Example

$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../src

Windows Examples

• Example direct build on Windows:

  cmake -G "Visual Studio <MSVC Version> <MSVC Product Year> Win<arch>" ../src -DCMAKE_BUILD_TYPE=Release
  cmake --build . --target ALL_BUILD --config Release
  

• Example cmake commands using x86:

  cmake -G "Visual Studio <MSVC Version> <MSVC Product Year> Win32" ../src -DCMAKE_BUILD_TYPE=Release
  

  MSVC Mapping

  MSVC Product Year	MSVC Version
  2022	17
  2019	16
  2017	15.9
  	15.8
  	15.7
  	15.6
  	15.5
  	15.4 - 15.3
  	15.2 - 15.0
  2015	14
  2013	12
  2012	11

Example build commands for Arch x86, MSVC Year 2017, MSVC Version 15:

cmake -G “Visual Studio 15 2017 Win32” ../src

Example build commands forArch x64, MSVC Year 2019, MSVC Version 16:

cmake -G “Visual Studio 16 2019” -A x64 ../src -DCMAKE_BUILD_TYPE=Release

cmake -G “Visual Studio 15 2017 Win64” ../src -DCMAKE_BUILD_TYPE=Release