Build System and Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The gr-cuda project utilizes a CMake-based build system designed to integrate high-performance C++/CUDA kernels with the GNU Radio framework and Python-based CuPy blocks. The build system manages a complex polyglot environment involving C++17, CUDA, and Python, ensuring that hardware-accelerated signal processing blocks are correctly compiled, bound to Python, and deployed to various environments like Conda or PyBOMBS.
The primary goal of the build system is to provide a "zero-copy" GPU pipeline by managing cuda_buffer objects and CUDA VMM-based circular buffers while maintaining compatibility with standard GNU Radio (3.10+) OOT (Out-Of-Tree) module structures.
Sources: CMakeLists.txt:14-25, README.md:1-15
Build Architecture and Configuration
The project is structured into logical subdirectories handled by CMake, separating headers, core C++/CUDA logic, Python bindings, and GNU Radio Companion (GRC) definitions.
The diagram shows the hierarchical relationship of the CMake project structure and its output artifacts.
Key Build Requirements
The build system mandates specific toolchain versions to support CUDA and C++ modern features:
| Component | Minimum Version | Note |
|---|---|---|
| CMake | 3.18 | Required for modern CUDA integration |
| C++ Standard | 17 | Used for core library logic |
| C Standard | 11 | Used for compatibility |
| CUDA Toolkit | 10.2 | Required for VMM and device pointers |
| GNU Radio | 3.10 | Target framework version |
Sources: CMakeLists.txt:14-16, CMakeLists.txt:68-81, README.md:28-34
Core Library Compilation (lib/gnuradio-cuda)
The C++ core, located in the lib/ directory, compiles both standard C++ source files (.cc) and CUDA source files (.cu) into a single shared library named gnuradio-cuda.
CUDA Architecture Support
The system defaults to native architecture detection, allowing the compiler to optimize for the build machine's GPU. Users can override this by passing -DCMAKE_CUDA_ARCHITECTURES (e.g., "86" for Ampere).
Sources: lib/CMakeLists.txt:81-91
Linking Dependencies
The shared library links against several critical system and framework components:
gnuradio::gnuradio-runtime: Core GNU Radio scheduler support.CUDA::cudart: CUDA Runtime.CUDA::cuda_driver: Low-level driver API (required for VMM).CUDA::cufft: Hardware-accelerated FFT support.
Sources: lib/CMakeLists.txt:53-60
Python Integration and Bindings
The project exposes its C++ GPU blocks to Python through pybind11 and integrates with CuPy for pure-Python GPU block development.
Bindings Generation
The python/cuda/bindings directory uses GR_PYBIND_MAKE_OOT to generate Python wrappers. A custom target, copy_bindings_for_tests, ensures the compiled .so files are available in the build directory for immediate testing before installation.
Sources: python/cuda/bindings/CMakeLists.txt:48-60
Binding Integrity Verification
To prevent "footguns" where C++ headers are modified without updating Python bindings, the project includes a specialized script to verify MD5 hashes of headers recorded in the binding files.
Process for ensuring Python bindings stay synchronized with C++ header changes.
Sources: scripts/check_bindtool_header_hashes.py:10-25, scripts/check_bindtool_header_hashes.py:102-120
Testing and Deployment
Automated Testing
The build system integrates with CTest and Pytest. Unit tests cover both C++ logic and Python/CuPy block functionality.
- C++ Tests: Registered via
GR_ADD_CPP_TEST. - Python Tests: Defined in
qa_*.pyfiles and registered viaGR_ADD_TEST. - Python Environment: Configured in
pyproject.tomlusingrufffor linting andpytestfor discovery.
Sources: lib/CMakeLists.txt:112-123, python/cuda/CMakeLists.txt:39-140, pyproject.toml:1-10
Installation and Deployment
The project supports various installation prefixes and environments:
- Standard Installation: Defaults to
/usr/localor the GNU Radio prefix. - PyBOMBS: Automatically detects
$PYBOMBS_PREFIXand sets the installation path accordingly. - Conda: Instructions recommend using
-DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"to deploy within virtual environments.
Sources: CMakeLists.txt:28-36, README.md:43-46
Target Directories
Files are deployed to the following standard GNU Radio locations:
- Headers:
include/gnuradio/cuda - Libraries:
lib/(withLIB_SUFFIXsupport) - Python Modules:
${GR_PYTHON_DIR}/gnuradio/cuda - GRC Blocks:
share/gnuradio/grc/blocks
Sources: CMakeLists.txt:104-115, include/gnuradio/cuda/CMakeLists.txt:14-34, grc/CMakeLists.txt:11-34
Summary
The gr-cuda build system is a robust CMake-based framework that automates the complexities of compiling CUDA kernels, linking against GNU Radio, and generating Python bindings. It enforces toolchain consistency through version checks and hash verification, while providing flexible deployment options for high-performance signal processing across development environments.