OpenCSD: Building with CMake

Build Modes

The CMake build now supports two modes:

  • OPENCSD_BUILD_MIN_LIB_STATIC=ON Minimal library/static-oriented build for integration into larger environments:

    • builds opencsd and opencsd_c_api
    • builds snapshot_parser and trc_pkt_lister when BUILD_TESTING=ON

  • provides install and uninstall targets for the minimal library target set only

  • OPENCSD_BUILD_MIN_LIB_STATIC=OFF Full project build and default mode:

    • builds shared and static libraries
    • builds the additional full project test/helper targets
    • defaults BUILD_TESTING to ON
    • installs the manpage and provides uninstall
    • writes outputs into decoder/lib/builddir, decoder/tests/lib/builddir, and decoder/tests/bin/builddir when OPENCSD_FULL_PROJECT_LAYOUT=ON

Recommended Build Commands

From the repository root:

The top-level CMakeLists.txt uses support templates from decoder/build/cmake/.

Linux and Other Single-Config Generators

Minimal integration build:

cmake -S . -B build-original -G "Unix Makefiles" -DBUILD_TESTING=ON -DOPENCSD_BUILD_MIN_LIB_STATIC=ON
cmake --build build-original -j

Full project build:

cmake -S . -B build -G "Unix Makefiles" -DBUILD_TESTING=ON
cmake --build build -j

Useful variants:

cmake -S . -B build-debug -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
cmake --build build-debug -j

cmake -S . -B build-release -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
cmake --build build-release -j

Install from an out-of-source build:

cmake --install build --prefix /your/install/prefix

Clean only build outputs:

cmake --build build --target clean

Remove the entire generated build and configuration state:

rm -rf build

Windows with Visual Studio 2022

Use a Visual Studio 2022 generator and pass a configuration at build time. The helper script and the direct commands below default to x64.

Full project build:

cmake -S . -B build-vs2022 -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTING=ON
cmake --build build-vs2022 --config Release --parallel

Minimal integration build:

cmake -S . -B build-vs2022-min -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTING=ON -DOPENCSD_BUILD_MIN_LIB_STATIC=ON
cmake --build build-vs2022-min --config Release --parallel

Debug build:

cmake -S . -B build-vs2022-debug -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTING=ON
cmake --build build-vs2022-debug --config Debug --parallel

Install from an out-of-source build:

cmake --install build-vs2022 --config Release --prefix C:\temp\opencsd-install

Python Helper Script

The helper script decoder/build/cmake/build_cmake.py wraps configure, build, install and uninstall flows. It can be invoked either from the repository root or from decoder/build/cmake/. If --build-dir is omitted, the script creates and reuses mode-specific build directories under decoder/build/cmake/.

On Windows, the script defaults to the Visual Studio 17 2022 generator, selects the x64 platform for Visual Studio builds, and uses the Visual Studio bundled cmake.exe if cmake is not already on PATH. On non-Windows hosts, the default generator remains Unix Makefiles.

Example Commands

Configure and build a minimal library tree:

python3 decoder/build/cmake/build_cmake.py --minimal

Run the CMake clean target and then remove a build tree:

python3 decoder/build/cmake/build_cmake.py --build-dir decoder/build/cmake/build-cmake-min --clean-all

Run the generated CMake clean target on an existing build tree:

python3 decoder/build/cmake/build_cmake.py --build-dir decoder/build/cmake/build-cmake-min --clean

Configure and build a debug tree:

python3 decoder/build/cmake/build_cmake.py --debug

Configure, build, and install a minimal tree:

python3 decoder/build/cmake/build_cmake.py --minimal --install --install-prefix /tmp/opencsd-install

Reuse a previously configured build tree and build it without reconfiguring:

python3 decoder/build/cmake/build_cmake.py --build-dir decoder/build/cmake/build-cmake-min --no-configure

Install from a previous build without reconfiguring or rebuilding:

python3 decoder/build/cmake/build_cmake.py --build-dir decoder/build/cmake/build-cmake-min --install-only --install-prefix /tmp/opencsd-install

Uninstall from a previous build without reconfiguring or rebuilding:

python3 decoder/build/cmake/build_cmake.py --build-dir decoder/build/cmake/build-cmake-min --uninstall-only

Windows full build from a plain PowerShell prompt:

py -3 decoder/build/cmake/build_cmake.py --build-testing ON

Windows debug build:

py -3 decoder/build/cmake/build_cmake.py --debug --build-testing ON

Windows minimal build:

py -3 decoder/build/cmake/build_cmake.py --minimal --build-testing ON

Options

  • -h, --help: Show the command help and exit.
  • --build-dir BUILD_DIR: Use the given out-of-source build directory. If omitted, the script chooses a default under decoder/build/cmake/, such as decoder/build/cmake/build-cmake, decoder/build/cmake/build-cmake-min, or decoder/build/cmake/build-cmake-min-debug.
  • --generator GENERATOR: Pass an explicit CMake generator. The default is platform-specific: Visual Studio 17 2022 on Windows, Unix Makefiles elsewhere.
  • --platform PLATFORM: Pass a CMake platform via -A for Visual Studio generators. The default is x64 for Windows Visual Studio builds.
  • --debug: Use a Debug build. For single-config generators this sets -DCMAKE_BUILD_TYPE=Debug; for multi-config generators it selects --config Debug.
  • --config {Debug,Release}: Explicit build configuration. Defaults to Release, or Debug when --debug is set.
  • --minimal: Configure with -DOPENCSD_BUILD_MIN_LIB_STATIC=ON.
  • --jobs JOBS: Pass a parallelism level to cmake --build --parallel.
  • --configure-only: Run only the CMake configure step.
  • --clean-all: Run the generated CMake clean target on an existing configured build tree, then remove the selected build directory before any other action. If no other action is requested, the script performs both cleanup steps and exits.
  • --clean: Run the generated CMake clean target from an already configured build tree without configuring or building.
  • --no-configure: Reuse an existing configured build tree and skip configure. The selected build directory must already contain CMakeCache.txt.
  • --no-build: Skip cmake --build. Use this when running --install or --uninstall against an already built tree.
  • --install: Run cmake --install after configure/build.
  • --install-only: Run cmake --install from an already configured build tree without configuring or building.
  • --install-prefix INSTALL_PREFIX: Pass an installation prefix to cmake --install. This requires --install or --install-only.
  • --uninstall: Run the generated uninstall target after the main action.
  • --uninstall-only: Run the generated uninstall target from an already configured build tree without configuring or building.
  • --build-testing {ON,OFF}: Set BUILD_TESTING explicitly instead of using the project default.
  • --full-project-layout {ON,OFF}: Set OPENCSD_FULL_PROJECT_LAYOUT explicitly instead of using the project default.

Option Constraints

  • --configure-only and --no-configure cannot be used together.
  • --clean-all cannot be combined with --no-configure.
  • --clean-all cannot be combined with --no-build.
  • --clean-all cannot be combined with --clean.
  • --platform is only valid with Visual Studio generators.
  • --install-prefix requires --install or --install-only.
  • --debug cannot be combined with --config Release.
  • --no-build cannot be combined with --configure-only.
  • --no-build must be paired with one of --install or --uninstall.
  • --clean requires an existing configured build directory.
  • --clean cannot be combined with --configure-only, --no-configure, --no-build, --install, --install-only, --uninstall, or --uninstall-only.
  • --clean-all will run the CMake clean target first when the selected build directory is configured, then remove the build directory itself.
  • --install-only and --uninstall-only both require an existing configured build directory.
  • --install-only cannot be combined with --install, --no-configure, --no-build, --configure-only, or --uninstall.
  • --uninstall-only cannot be combined with --uninstall, --no-configure, --no-build, --configure-only, or --install.