README.md

Note The instructions in this README are specific to Linux development environments. Instructions for Windows are coming soon!

CCCL Dev Containers

CCCL uses Development Containers to provide consistent and convenient development environments for both local development and for CI. This guide covers setup in Visual Studio Code and Docker. The guide also provides additional instructions in case you want use WSL.

Table of Contents

1. Quickstart: VSCode (Recommended)
2. Quickstart: Docker (Manual Approach)
3. Quickstart: Using WSL

Quickstart: VSCode (Recommended)

Prerequisites

• 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

Steps

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 the Command Palette to start a Dev Container. Press Ctrl+Shift+P to open the Command Palette. 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. Once initialized, the local cccl/ directory is mirrored into the container to ensure any changes are persistent.

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

(Optional) Authenticate with GitHub for sccache

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.

Quickstart: Docker (Manual Approach)

Prerequisites

• Docker

Steps

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.

Available Environments

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.

VSCode Customization

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.

GitHub Codespaces

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:

For Maintainers: The make_devcontainers.sh Script

Overview

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

How It Works:

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.

Quickstart: Using WSL

Note

Make sure you have the Nvidia driver installed on your Windows host before moving further. Type in nvidia-smi for verification.

Install WSL on your Windows host

Warning

Disclaimer: This guide was developed for WSL 2 on Windows 11.

1. Launch a Windows terminal (e.g. Powershell) as an administrator.

2. Install WSL 2 by running:

wsl --install

This should probably install Ubuntu distro as a default.

3. Restart your computer and run wsl -l -v on a Windows terminal to verify installation.

Install prerequisites and VS Code extensions

4. Launch your WSL/Ubuntu terminal by running wsl in Powershell.

5. Install the WSL extension on VS Code.

   • Ctrl + Shift + P and select WSL: Connect to WSL (it will prompt you to install the WSL extension).

   • Make sure you are connected to WSL with VS Code by checking the bottom left corner of the VS Code window (should indicate "WSL: Ubuntu" in our case).

6. Install the Dev Containers extension on VS Code.

   • In a vanilla system you should be prompted to install Docker at this point, accept it. If it hangs you might have to restart VS Code after that.

7. Install the NVIDIA Container Toolkit. Make sure you install the WSL 2 version and not the native Linux one. This builds on top of Docker so make sure you have Docker properly installed (run docker --version).

8. Open /etc/docker/daemon.json from within your WSL system (if the file does not exist, create it) and add the following:

{
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

then run sudo systemctl restart docker.service.

---

Build CCCL in WSL using Dev Containers

9. Still on your WSL terminal run git clone https://github.com/NVIDIA/cccl.git

10. Open the CCCL cloned repo in VS Code ( Ctrl + Shift + P , select File: Open Folder... and select the path where your CCCL clone is located).

11. If prompted, choose Reopen in Container.

    • If you are not prompted just type Ctrl + Shift + P and Dev Containers: Open Folder in Container ....

12. Verify that Dev Container was configured properly by running nvidia-smi in your Dev Container terminal. For a proper configuration it is important for the steps in Install prerequisites and VS Code extensions to be followed in a precise order.

From that point on, the guide aligns with our existing Dev Containers native Linux guide with just one minor potential alteration:

13. If WSL was launched without the X-server enabled, when asked to "authenticate Git with your Github credentials", if you answer Yes, the browser might not open automatically, with the following error message.

Failed opening a web browser at https://github.com/login/device exec: "xdg-open,x-www-browser,www-browser,wslview": executable file not found in $PATH Please try entering the URL in your browser manually

In that case type in the address manually in your web browser https://github.com/login/device and fill in the one-time code.