Contributor Docs#

Thank you for your interest in contributing to the CUDA Core Compute Libraries (CCCL)! This section covers the branching, build, test, debug, pull request, and review workflows a CCCL contributor uses day to day.

Looking for ideas for your first contribution? Check out the good first issue label.

Getting Started#

  1. Fork & Clone the Repository:

    Fork the CCCL GitHub Repository and clone the fork. For more information, check GitHub’s documentation on forking and cloning a repository.

  2. Set up Development Environment:

    CCCL uses Development Containers to provide a consistent development environment for both local development and CI. Contributors are strongly encouraged to use these containers as they simplify environment setup. See the Dev Containers guide for instructions on how to quickly get up and running using dev containers with or without VSCode.

Making Changes#

  1. Create a New Branch:

    git checkout -b your-feature-branch

  2. Make Changes.

  3. Build and Test:

    Ensure changes don’t break existing functionality by building and running tests.

    ./ci/build_[thrust|cub|libcudacxx].sh -cxx <HOST_COMPILER> -std <CXX_STANDARD> -arch <GPU_ARCHS>

# test implies build
./ci/test_[thrust|cub|libcudacxx].sh  -cxx <HOST_COMPILER> -std <CXX_STANDARD> -arch <GPU_ARCHS>

    For more details on building and testing, refer to the Building and Testing section below.

  4. Commit Changes:

    git commit -m "Brief description of the change"

    If you are a member of the NVIDIA GitHub enterprise, please sign your commits.

Developer Guides#

For more information about architecture, design, and development practices, consult the following developer guides:

Building and Testing#

CCCL components are header-only libraries. This means there isn’t a traditional build process for the library itself. However, before submitting contributions, it’s a good idea to build and run tests.

There are multiple options for building and running our tests, and which one you should reach for depends on your goal (fixing a single test vs. reproducing a full CI job) and whether you are using a Dev Container (highly recommended!). See Install, Build, Test for the full breakdown of available tools.

Manual build scripts#

ci/build_<project>.sh and ci/test_<project>.sh build or test a whole project (thrust, cub, or libcudacxx) for a given host compiler, C++ standard, and GPU architecture set. These are the scripts our CI runs, so they reproduce a CI job exactly:

./ci/build_cub.sh -cxx g++ -std 17 -arch "70;75;80-virtual"
./ci/test_cub.sh  -cxx g++ -std 17 -arch "70;75;80-virtual"

Building tests does not require a GPU; running them does. See Install, Build, Test for the full script reference, including the faster, target-scoped ci/util/build_and_test_targets.sh for iterating on a single test, and Architecture flags for the -arch value syntax.

Using CMake Presets#

CCCL also ships CMake Presets for configuring, building, and testing directly with cmake/ctest. See Preset reference for the full preset reference, including how to list presets and how preset build output is laid out on disk.

See Using CMake Presets via VS Code GUI extension for the recommended, GUI-driven way to use CMake Presets from VS Code when working inside a Dev Container.

Pre-commit hooks (code formatting, etc.)#

CCCL uses pre-commit to execute all code linters and formatters. These tools ensure a consistent coding style throughout the project. Using pre-commit ensures that linter versions and options are aligned for all developers. Additionally, there is a CI check in place to enforce that committed code follows our standards.

The linters used by CCCL are listed in .pre-commit-config.yaml. For example, C++ and CUDA code is formatted with clang-format.

To enable the use of pre-commit, install via conda or pip:

conda config --add channels conda-forge
conda install pre-commit

pip install pre-commit

Then run pre-commit hooks before committing code:

pre-commit run

By default, pre-commit runs on staged files (only changes and additions that will be committed). To run pre-commit checks on all files, execute:

pre-commit run --all-files

It is recommended to set up the pre-commit hooks to run automatically when you make a git commit. This can be done by running:

pre-commit install

Now code linters and formatters will be run each time you commit changes.

You can skip these checks with git commit --no-verify or with the short version git commit -n.

Secret Scanning#

The secret-scan-trufflehog pre-commit hook scans staged files and installs TruffleHog on first run (use Git Bash on Windows). If it flags a secret, remove it before committing, or contact a maintainer if it’s a false positive. Secrets are also scanned server-side in CI on main.

Creating a Pull Request#

Push the local branch with your changes to your fork on GitHub:

git push origin your-feature-branch

See Creating a Pull Request for further instructions.

Review Process#

Once submitted, maintainers will be automatically assigned to review the pull request. They might suggest changes or improvements. Constructive feedback is a part of the collaborative process, aimed at ensuring the highest quality code.

For constructive feedback and effective communication during reviews, we recommend following Conventional Comments.

Further recommended reading for successful PR reviews:

We welcome the use of AI tools to assist in code authoring and code review. However, the (human) CCCL maintainers must understand a contribution and its impact in order to own and maintain it. As the author, motivate your change and help the reviewer build a mental model of it, for example with drawings, benchmarks, or additional tests and documentation. Careful review is how we sustain the stability, quality, and performance the CUDA community relies on.

Thank You#

Your contributions enhance CCCL for the entire community. We appreciate your effort and collaboration!