Note The instructions in this README are specific to Linux development environments (including WSL on Windows). Instructions for native Windows development (e.g., msvc) are coming soon!

CCCL uses Dev Containers to provide consistent and convenient development environments for both local development and for CI.

VSCode offers the most convenient experience with Dev Containers due to its tight native integration, however, our containers are also fully usable without VSCode by leveraging Docker directly.

1. Quickstart: VSCode on Linux (Recommended)
2. Quickstart: VSCode on WSL (Recommended for Windows)
3. Quickstart: Docker on Linux (Manual Approach)

• Visual Studio Code
• Remote - Containers extension
• NVIDIA Container Toolkit
• Docker - This is only for completeness because it should already be implicitly installed by the Dev Containers extension

• Supported NVIDIA GPU
• NVIDIA Driver
• NVIDIA Container Toolkit

1. Clone the Repository

   git clone https://github.com/nvidia/cccl.git

2. Open the cloned directory in VSCode

3. Launch a Dev Container by clicking the prompt suggesting to "Reopen in Container"

   

   • Alternatively, use ctrl+shift+p to open the Command Palette and type "Remote-Containers: Reopen in Container" and select it.

     

4. Select an environment with the desired CTK and host compiler from the list:

   

5. VSCode will initialize the selected Dev Container. This can take a few minutes the first time.

6. (Optional) Authenticate with GitHub

   • After container startup, you will be asked if you would like to authenticate with GitHub. This is for access to CCCL's distributed sccache storage. If you are not an NVIDIA employee, you can safely ignore this step. For more information, see the sccache section below.

7. Once initialized, the local cccl/ directory is mirrored into the container to ensure any changes are persistent.

8. Done! See the contributing guide for instructions on how to build and run tests.

After starting the container, there will be a prompt to authenticate with GitHub. This grants access to a sccache server shared with CI and greatly accelerates local build times. This is currently limited to NVIDIA employees belonging to the NVIDIA or rapidsai GitHub organizations.

Without authentication to the remote server, sccache will still accelerate local builds by using a filesystem cache.

Follow the instructions in the prompt as below and enter the one-time code at https://github.com/login/device

To manually trigger this authentication, execute the devcontainer-utils-vault-s3-init script within the container.

For more information about the sccache configuration and authentication, see the documentation at rapidsai/devcontainers.

Windows Subsystem for Linux (WSL) enables you to run a Linux environment directly in Windows. This isn't for native Windows development (e.g., compiling with msvc), but effectively a more convenient option than setting up a dual-boot Linux/Windows machine. Apart from the initial setup of WSL, the process for using CCCL's Dev Containers in WSL is effectively the same as the instructions for Linux, because WSL is Linux.

• Windows OS that supports WSL 2 (Windows 11 or newer)
• Windows Subsystem for Linux v2 (WSL 2)
• Visual Studio Code (installed on Windows host)
• VSCode Remote Development Extension Pack (installed on Windows host)
  • Includes Dev Containers and WSL extensions
• Docker - (Will be installed automatically by the Remote Development extension)

• Supported NVIDIA GPU
• NVIDIA Driver (installed on Windows host)
• NVIDIA Container Toolkit (installed inside WSL)

For more details see the official NVIDIA Getting Started with CUDA on WSL guide.

Refer to Microsoft's documentation for the full instructions to install WSL2.

> wsl --install

> wsl -l -v
  NAME      STATE           VERSION
* Ubuntu    Running         2

# In Powershell, start WSL, which will drop you into a terminal session running in Linux
> wsl

# In the new terminal session, verify your Linux environment by changing to your home directory
# and displaying the current directory. This should show `/home/*YOUR USER NAME*`
> cd ~
> pwd
/home/jhemstad

$ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
$ sudo apt-get update
$ sudo apt-get install -y nvidia-container-toolkit

$ sudo nvidia-ctk runtime configure --runtime=docker
$ sudo systemctl restart docker

$ nvidia-smi

1. Launch VSCode on your Windows host

2. Connect VSCode to your WSL instance

• Enter ctrl + shift + p to open the command prompt and type "WSL" and click "WSL: Connect to WSL"
  • If you don't see this option, you need to install the WSL VSCode Extension (comes with the Remote Development pack )
  • To verify VSCode is connected to WSL, you should see the following in the bottom left corner:

3. VSCode is now attached to WSL and it is equivalent to running in a native Linux environment. You can now proceed as described in the section above.

• Docker

• Supported NVIDIA GPU
• NVIDIA Driver
• NVIDIA Container Toolkit

1. Clone the repository and use the launch.sh script to launch the default container environment

   git clone https://github.com/nvidia/cccl.git
   cd cccl
   ./.devcontainer/launch.sh --docker

   This script starts an interactive shell as the coder user inside the container with the local cccl/ directory mirrored into /home/coder/cccl.

   For specific environments, use the --cuda and --host options:

   ./.devcontainer/launch.sh --docker --cuda 12.2 --host gcc10
   

   See ./.devcontainer/launch.sh --help for more information.

2. Done. See the contributing guide for instructions on how to build and run tests.

CCCL provides environments for both the oldest and newest supported CUDA versions with all compatible host compilers.

Look in the .devcontainer/ directory to see the available configurations. The top-level devcontainer.json serves as the default environment. All devcontainer.json files in the cuda<CTK_VERSION>-<HOST-COMPILER> sub-directories are variations on this top-level file, with different base images for the different CUDA and host compiler versions.

By default, CCCL's Dev Containers come with certain VSCode settings and extensions configured by default, as can be seen in the devcontainer.json file. This can be further customized by users without needing to modify the devcontainer.json file directly.

For extensions, the dev.containers.defaultExtensions setting allows listing extensions that will always be installed.

For more general customizations, VSCode allows using a dotfile repository. See the VSCode documentation for more information.

One of the benefits of Dev Containers is that they integrate natively with GitHub Codespaces. Codespaces provide a VSCode development environment right in your browser running on a machine in the cloud. This provides a truly one-click, turnkey development environment where you can develop, build, and test with no other setup required.

Click the badge above or click here to get started with CCCL's Dev Containers on Codespaces. This will start the default Dev Container environment. Click here to start a Codespace with a particular environment and hardware configuration as shown:

make_devcontainers.sh generates devcontainer configurations for the unique combinations of CUDA Toolkit (CTK) versions and host compilers in ci/matrix.yaml.

1. Parses the matrix from ci/matrix.yaml.
2. Use the top-level .devcontainer/devcontainer.json as a template. For each unique combination of CTK version and host compiler, generate a corresponding devcontainer.json configuration, adjusting only the base Docker image to match the desired environment.
3. Place the generated configurations in the .devcontainer directory, organizing them into subdirectories following the naming convention cuda<CTK_VERSION>-<COMPILER_VERSION>.

For more information, see the .devcontainer/make_devcontainers.sh --help message.

Note: When adding or updating supported environments, modify matrix.yaml and then rerun this script to synchronize the devcontainer configurations.