How nvidia/cccl works
Main Modules and Components
• Core CUDA Libraries (the “engine”):
– Thrust: A high-level C++ parallel algorithms library that enables performance portability and productivity.
– CUB: A low-level, CUDA‐specific library designed for “block,” “warp,” and device–wide parallel primitives.
– libcudacxx: The CUDA C++ Standard Library that brings standard library functionality to both host and device code, including support for atomics, synchronization primitives, and more.
These three components reside in their own directories (thrust, cub, libcudacxx) and share a common, synchronized version. They are the heart of CCCL.
• Build and Integration Infrastructure:
– CMake Build System: At the top level you have CMakeLists.txt and the “cmake” directory. These configure and drive compilation, installation rules, and integration into downstream projects.
– Dev Containers: In the “.devcontainer” directory, multiple configurations (with various CUDA/C++ compiler combinations) ensure that developers always have a tested and reproducible environment. This is critical for local development and debugging.
– CI Pipeline: The “.github” directory contains GitHub Actions workflows (and various scripts in “ci/”) that build, test, run benchmarks, and generate documentation across a matrix of build configurations, CUDA Toolkit versions, and host compilers. This continuous integration layer is responsible for verifying both API and ABI stability on supported platforms.
• Testing, Benchmarks, and Examples:
– Testing: A dedicated “test” directory along with unit test directories under “python/…/tests” and “thrust/testing” ensure that every release is verified with a comprehensive test suite.
– Benchmarks: The “benchmarks” directory contains performance tests, scripts, and cmake configurations to measure the efficiency of parallel primitives.
– Examples: Under “examples/” there are several demonstrative projects (basic, cudax, cudax_stf) illustrating how to use CCCL in varied contexts.
• Language Bindings and Documentation:
– Python Bindings: Under “python/”, several folders (e.g. “cuda_cccl”, “cuda_cooperative”, “cuda_parallel”) provide Python interfaces into CCCL functionality, enabling rapid prototyping and integration with Python workflows.
– Documentation: The “docs” directory holds both user and developer documentation (including migration guides, API overviews, and tutorials). This is key for external users and contributors.
• Versioning and Compatibility Interfaces:
– Public API and ABI Versioning: Through header constants (e.g. CCCL_MAJOR_VERSION, CCCL_MINOR_VERSION, CCCL_PATCH_VERSION) and inline namespaces for CUDA’s ABI versioning (particularly in libcudacxx) the project ensures strict version control and compatibility. This “versioning layer” communicates compatibility with specific CUDA Toolkit versions.
Relationships and Interactions
◉ The Core libraries (Thrust, CUB, and libcudacxx) are designed to be used in a “header-only” mode. This means that when a developer writes CUDA C++ code, they include the appropriate headers (e.g., <thrust/device_vector.h>, <cub/cub.cuh>, or <cuda/std/atomic>) and the implementation gets merged at compile time.
◉ The Build system orchestrates the integration of these libraries via CMake. The CMake infrastructure is responsible for setting up include directories, compiler flags (including for device code and host code), and linking (if any non-header parts exist, such as precompiled artifacts with respect to versioning).
◉ During development, developers work in Dev Containers configured in “.devcontainer” which mimic the production build environment – ensuring consistent compiler versions and CUDA configurations.
• Top Layer (“Interface”): Developer Applications and Python bindings.
• Lower Layer (“Build/Integration Infrastructure”): CMake build system, CI Pipeline, and Development Environments (Dev Containers).
• Developer code includes the headers from Thrust/CUB/libcudacxx.
• The Python modules call into the CUDA core libraries.
• The CI pipeline triggers builds that invoke CMake, which in turn compiles the core libraries and runs tests.
• Test/Examples/Documentation (perhaps in a lighter tone.
– Label external tools and integration points:
• “GitHub CI / GitHub Actions” as the engine running tests and building documentation.
• “CMake” as the configuration/build tool.
• “nvcc” and supported host compilers to show compilation flow.
• Optionally, show links to external package managers like conda.
– Note the header-only design:
• That most functionality is included via headers (so no runtime linking issues, but API and ABI versioning is handled at compile time with inline namespaces and macros).