- Generated by
1.17.0
|
libfreenect2 0.4
Open source driver for the Kinect for Windows v2 (K4W2) sensor
|
Everything needed to build, test, and contribute to libfreenect2 itself. For installing the library to use it, see Installing on macOS, Installing on Linux, or Installing on Windows.
| Tool | Version | Needed for |
|---|---|---|
| CMake | 3.16 or newer | building |
| C++ compiler | C++17 (the CI floor) | building |
| Ninja | any recent | recommended generator; CI uses it |
| Python | 3.12 or newer | repository Python tools and tests |
| uv | 0.12.x | Python dependency management |
| clang-format | 18 recommended | formatting C++ |
| clang-tidy | 18 | static analysis |
| Doxygen | any recent | building the documentation site |
Python is not needed to build or use the library. It is only needed for the repository's own tooling under tools/ and tests/python.
The repository's Python helper and maintenance scripts require Python 3.12 or newer, pinned by .python-version and enforced by requires-python in pyproject.toml. Dependencies are managed with uv.
Those four commands are exactly the CI Python gate. The Ruff policy matches pylibfreenect3: it targets Python 3.12, uses an 88-character line length, and enables the E, F, I, UP, B, SIM, RUF, and PT rule families. See Quality checks for the full rationale.
Build with the test suite and the CI warning gate enabled:
BUILD_TESTING=ON also builds freenect2_testlib, a second static library compiled from the same sources with default symbol visibility. The shipping freenect2 target uses hidden visibility, so its internal classes are not linkable from a test binary; the tests link the testlib instead. The shipping library is left untouched.
Unit tests are labelled, so ctest -L unit selects the fast subset — which is what the sanitizer profiles run.
These are development-only build options, defined in cmake_modules/QualityChecks.cmake and applied only to first-party targets. Third-party code fetched by the test suite is never instrumented.
| Option | Default | Effect |
|---|---|---|
| ENABLE_STRICT_WARNINGS | ON | The project's high-signal compiler warnings |
| ENABLE_WARNINGS_AS_ERRORS | OFF | Treat those warnings as errors (CI uses ON) |
| ENABLE_ASAN | OFF | AddressSanitizer |
| ENABLE_UBSAN | OFF | UndefinedBehaviorSanitizer |
| ENABLE_UBSAN_IMPLICIT_CONVERSIONS | OFF | Clang's implicit integer conversion checks |
| ENABLE_TSAN | OFF | ThreadSanitizer (cannot be combined with ASan) |
| ENABLE_COVERAGE | OFF | LLVM source coverage (Clang only) |
| ENABLE_FUZZING | OFF | libFuzzer targets (Clang only; forces BUILD_TESTING and ENABLE_ASAN) |
| ENABLE_STDLIB_HARDENING | OFF | Standard-library runtime assertions |
| ENABLE_SANITIZERS | OFF | Compatibility alias that forces ENABLE_ASAN + ENABLE_UBSAN |
| ENABLE_PROFILING | OFF | Collect profiling stats (memory consuming) |
Each profile needs its own build directory. Full recipes — including the ASAN_OPTIONS/TSAN_OPTIONS the CI uses, fuzzing corpora, and coverage report generation — are in Quality checks.
Do not set ENABLE_STRICT_WARNINGS=OFF to land warning-producing first-party code; it exists only for diagnosing a compiler that does not understand the project warning set.
C++ formatting is governed by .clang-format. CI runs an advisory git clang-format check over changed lines only:
clang-tidy runs against a compile database (.clang-tidy holds the checks), and a focused Semgrep policy lives at tools/quality/semgrep.yml:
The site uses Doxygen 1.17 with the vendored Doxygen Awesome base theme. With Doxygen installed, the doc target is added automatically:
Output lands under build-doc/doc/html. The published site is built from master by the Documentation workflow and served from https://hbmartin.github.io/libfreenect2-metal/.
Top-level doc/*.md files are discovered automatically. Give every new guide a stable Doxygen anchor in its level-one title (# Title {#anchor}), then add it to exactly one Guides group in doc/DoxygenLayout.xml and to the matching card in doc/guides.dox. The doc target fails if a Markdown page lacks an anchor, has no navigation entry, appears more than once, or generates a duplicate raw file-reference page.
The CI workflow runs on every push to master and every pull request:
| Job | What it covers |
|---|---|
| python-quality | Ruff lint, Ruff format, pytest |
| build-test-metal | AppleClang on self-hosted macOS: C++17, Metal, warnings-as-errors, hardened stdlib, Metal/CPU parity tests |
| linux-builds | GCC and Clang × shared and static |
| linux-filter-backends | Depth filter backend combinations |
| linux-vaapi | VAAPI JPEG decoding |
| sanitizers | ASan + UBSan, TSan |
| fuzzers | Bounded libFuzzer smoke run |
| coverage | LLVM source coverage |
| format | git clang-format on changed lines (advisory) |
| semgrep | Focused policy scan |
| static-analysis | clang-tidy 18 |
Pull requests from forks never execute on the persistent self-hosted runner, so the Metal job is skipped there. See Self-hosted macOS CI runner setup for that runner's setup. Additional scheduled workflows cover deep analysis and hardware soak testing.
1.17.0