Devcontainer overview#

CCCL devcontainers package a CUDA toolkit and host compiler into a Docker image that matches a CI environment exactly. The same image that builds and tests a project in GitHub Actions runs on a developer’s machine. Reproducing a CI result locally requires no guesswork about toolchain versions: pick the combination, launch the container, and the compiler, CTK, and supporting tools are identical to what CI used.

Two uses: local development and CI#

Local development. Open the repository in VSCode and select a devcontainer from the picker, or launch one directly with .devcontainer/launch.sh. launch.sh reference covers launch.sh flags and the available combinations. launch.sh --docker runs the container without VSCode and drops into a shell or runs a script. Without --docker, it opens the container in VSCode.

CI. GitHub Actions runs the identical images. A CI job for a given CTK and compiler combination builds and tests inside the same rapidsai/devcontainers image a developer would launch locally.

Image source: rapidsai/devcontainers#

The base images are built and published by the rapidsai/devcontainers repository, not by CCCL. Each image bundles a CUDA toolkit, a host compiler, and development tooling. CCCL references these images by tag; it does not build them.

Image tags follow the pattern rapidsai/devcontainers:<version>-cpp-<compiler><version>-cuda<ctk>[ext]. The -cuda<ctk> segment is present for every combination except nvhpc, which bundles its own CUDA toolkit; nvhpc images omit it. The <version> tag is defined in ci/matrix.yaml under devcontainer_version. A generated .devcontainer/<combo>/devcontainer.json contains the resolved tag for any given combination.

This upstream dependency gates toolchain changes. Adding a CUDA toolkit version or a host compiler requires the matching image to exist in rapidsai/devcontainers first. The sequence is:

  1. Update rapidsai/devcontainers to build and publish images for the new combination.

  2. Update CCCL’s ci/matrix.yaml to reference the new version.

  3. Regenerate CCCL’s devcontainer configs to match all matrix workflow requirements.

Adding a new devcontainer toolchain has additional details on this process.