Building from source

This section describes how to compile cwipc from the GitHub repository on macOS, Linux or Windows. The project uses CMake with a vcpkg‑based third dependency tree.

If you want to build offline (i.e. without cloning the repository) you must download the cwipc--fullsource archive, either as .zip or .tar.gz, from the releases page. The standard GitHub Source code downloads do not include the submodules therefore they will not work.

Prerequisites

  • A recent CMake (3.20+).

  • A C++17 compiler (clang, gcc, MSVC).

  • Git toolchain.

  • Python 3.12.

  • bash or zsh on macOS/Linux; PowerShell on Windows.

Building from the command line

  1. Clone the repository, ensuring you also pull the submodules and the git lfs content:

    git clone https://github.com/cwi-dis/cwipc.git
cd cwipc
git submodule update --init --recursive
git lfs init
git lfs pull

  2. Install third‑party packages:

    • macOS: scripts/install-3rdparty-macos.sh

    • Ubuntu: scripts/install-3rdparty-ubuntu2404.sh

    • Windows: scripts/install-3rdparty-windows.ps1 (run as Administrator).

  3. Configure and build with CMake presets:

    cmake --list-presets          # This shows the available presets on your current platform.
cmake --preset mac-production # or another one that is listed

    The presets automatically supply the vcpkg toolchain.

  4. Build the code (in the build subdirectory):

    cmake --build --preset mac-production

  5. (Optional) Run the unit tests:

    ctest --preset mac-production

  6. Install to a local prefix:

    cmake --install build --prefix ../cwipc-local-install

    The default prefix is /usr/local on Unix and C:\Program Files\cwipc on Windows; override with -DCMAKE_INSTALL_PREFIX when invoking cmake.

  7. Try it:

    On Windows you have to add the installed bin directory to your PATH environment variable. On Mac and Linux this is optional (because the programs use rpath to find the shared libraries).

Building from vscode

Easiest is to do all development from Visual Studio Code, vscode for short. Get that. You also want to get your standard C/C++ compilers and such, cmake and Python (3.12 preferred).

On Windows use the Visual Studio Community Installer to get the compilers and cmake. Download Python and vscode yourself. Note:

  • you should install Python “For All Users”.

  • You should install into a writeable directory, such as C:/Python39 otherwise you will have to use Run as Administrator for various build steps.

On Linux use the system package manager for everything, except you may have to install vscode differently, use google to check.

On Mac use the XCode installer for the compilers, brew for cmake, and google for vscode.

For Android you will have to install the correct Android crosscompilers and all that.

When you have vscode working you want to install the following extensions for it:

  • C/C++ Tools and Extension Pack

  • CMake and CMake Tools

  • Python, Pylance and Python Debugger

Debugging

The cmake presets have a develop option for each platform. When you build these the vscode debuggers will work (both the native C/C++ debuggers and of course also the Python debugger).

After you have built cwipc, you should run (Mac, Linux):

source scripts/activate

Or, on Windows:

& scripts\activate.ps1

This will ensure you have the right build/bin directory on your PATH, and the right dynamic library search path, and the right Python venv activated with all the cwipc commands and modules available.

Some issues can then be debugged with the C or C++ command line utilities (by putting breakpoints at the right location and running them with the correct command line arguments).

Many issues are easier to debug with the Python scripts. There are some hooks in place to help with this.

All Python scripts accept a --debugpy command line option. This will pause the script at begin of run and you can attach the vscode Python debugger to the process.

All Python scripts also accept a --pausefordebug command line option. This will pause the script at begin of run (and end of run), waiting for you to press Y. While the script is paused you can obtain the process ID and attach the vscode C/C++ debugger to the process.

Additionally, you can send SIGQUIT to all the Python scripts to cause them to dump the Python stacktraces of all threads.

Debugging from Unity

If you are using cwipc_unity you can set CwipcConfig.overrideNativeLoadPath to set an absolute path where the native libraries will be loaded from. If you set this to your build/bin directory (or build/bin/RelWithDebInfo on Windows) that works just fine. You can then attach the native debugger.

More Debugging features

The environment variable CWIPC_LOGGING allows you to control the level of log messages in the native code. Setting it to TRACE gives you moderate levels of output, DEBUG really requires you to know the code intimately.

For capturers, you can also set (in cameraconfig.json) system.debug to enable debug logging from the native cwipc libraries. (This will appear in the Unity console for Unity use).

For Kinect and Orbbec capturers you can also set system.apiDebug there, which will enable debug logging from the SDK. But you _really_ have to want this… :-)

Notes

  • Python bindings are built as part of the main build, and the wheels are saved in share/cwipc/python. The cwipc_pymodules_install.sh (or cwipc_pymodules_install.ps1) script can be used to install them.

  • To build Android targets, use the corresponding preset android-release.

Environment variables

  • CWIPC_VERSION can set the version string.

  • CWIPC_TEST_HAVE_KINECT_HARDWARE can be set to run the tests that require Azure Kinect hardware.

  • CWIPC_TEST_HAVE_ORBBEC_HARDWARE can be set to run the tests that require Orbbec hardware.

  • CWIPC_TEST_HAVE_REALSENSE2_HARDWARE can be set to run the tests that require Realsense2 hardware.