|
| 1 | +> **Note** |
| 2 | +> The instructions in this README are specific to Linux development environments. Instructions for Windows are coming soon! |
| 3 | +
|
| 4 | +[](https://codespaces.new/NVIDIA/cccl?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json) |
| 5 | + |
| 6 | +# CCCL Dev Containers |
| 7 | + |
| 8 | +CCCL uses [Development Containers](https://containers.dev/) to provide consistent and convenient development environments for both local development and for CI. This guide covers setup in [Visual Studio Code](#quickstart-vscode-recommended) and [Docker](#quickstart-docker-manual-approach). The guide also provides additional instructions in case you want use WSL. |
| 9 | + |
| 10 | +## Table of Contents |
| 11 | +1. [Quickstart: VSCode (Recommended)](#vscode) |
| 12 | +2. [Quickstart: Docker (Manual Approach)](#docker) |
| 13 | +3. [Quickstart: Using WSL](#wsl) |
| 14 | + |
| 15 | +## Quickstart: VSCode (Recommended) <a name="vscode"></a> |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | +- [Visual Studio Code](https://code.visualstudio.com/) |
| 19 | +- [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
| 20 | +- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) |
| 21 | +- [Docker](https://docs.docker.com/engine/install/) - This is only for completeness because it should already be implicitly installed by the Dev Containers extension |
| 22 | + |
| 23 | +### Steps |
| 24 | + |
| 25 | +1. Clone the Repository |
| 26 | + ```bash |
| 27 | + git clone https://github.com/nvidia/cccl.git |
| 28 | + ``` |
| 29 | +2. Open the cloned directory in VSCode |
| 30 | + |
| 31 | +3. Launch a Dev Container by clicking the prompt suggesting to "Reopen in Container" |
| 32 | + |
| 33 | +  |
| 34 | + |
| 35 | + - 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. |
| 36 | + |
| 37 | +  |
| 38 | + |
| 39 | +4. Select an environment with the desired CTK and host compiler from the list: |
| 40 | + |
| 41 | +  |
| 42 | + |
| 43 | +5. VSCode will initialize the selected Dev Container. This can take a few minutes the first time. |
| 44 | + |
| 45 | +6. Once initialized, the local `cccl/` directory is mirrored into the container to ensure any changes are persistent. |
| 46 | + |
| 47 | +7. Done! See the [contributing guide](../CONTRIBUTING.md#building-and-testing) for instructions on how to build and run tests. |
| 48 | + |
| 49 | +### (Optional) Authenticate with GitHub for `sccache` |
| 50 | + |
| 51 | +After starting the container, there will be a prompt to authenticate with GitHub. This grants access to a [`sccache`](https://github.com/mozilla/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. |
| 52 | + |
| 53 | +Without authentication to the remote server, `sccache` will still accelerate local builds by using a filesystem cache. |
| 54 | + |
| 55 | +Follow the instructions in the prompt as below and enter the one-time code at https://github.com/login/device |
| 56 | + |
| 57 | +  |
| 58 | + |
| 59 | +To manually trigger this authentication, execute the `devcontainer-utils-vault-s3-init` script within the container. |
| 60 | + |
| 61 | +For more information about the sccache configuration and authentication, see the documentation at [`rapidsai/devcontainers`](https://github.com/rapidsai/devcontainers/blob/branch-23.10/USAGE.md#build-caching-with-sccache). |
| 62 | + |
| 63 | +## Quickstart: Docker (Manual Approach) <a name="docker"></a> |
| 64 | + |
| 65 | +### Prerequisites |
| 66 | +- [Docker](https://docs.docker.com/desktop/install/linux-install/) |
| 67 | + |
| 68 | +### Steps |
| 69 | +1. Clone the repository and use the [`launch.sh`](./launch.sh) script to launch the default container environment |
| 70 | + ```bash |
| 71 | + git clone https://github.com/nvidia/cccl.git |
| 72 | + cd cccl |
| 73 | + ./.devcontainer/launch.sh --docker |
| 74 | + ``` |
| 75 | + This script starts an interactive shell as the `coder` user inside the container with the local `cccl/` directory mirrored into `/home/coder/cccl`. |
| 76 | + |
| 77 | + For specific environments, use the `--cuda` and `--host` options: |
| 78 | + ```bassh |
| 79 | + ./.devcontainer/launch.sh --docker --cuda 12.2 --host gcc10 |
| 80 | + ``` |
| 81 | + See `./.devcontainer/launch.sh --help` for more information. |
| 82 | + |
| 83 | +2. Done. See the [contributing guide](../CONTRIBUTING.md#building-and-testing) for instructions on how to build and run tests. |
| 84 | + |
| 85 | +## Available Environments |
| 86 | + |
| 87 | +CCCL provides environments for both the oldest and newest supported CUDA versions with all compatible host compilers. |
| 88 | + |
| 89 | +Look in the [`.devcontainer/`](.) directory to see the available configurations. The top-level [`devcontainer.json`](./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. |
| 90 | + |
| 91 | +## VSCode Customization |
| 92 | + |
| 93 | +By default, CCCL's Dev Containers come with certain VSCode settings and extensions configured by default, as can be seen in the [`devcontainer.json`](./devcontainer.json) file. This can be further customized by users without needing to modify the `devcontainer.json` file directly. |
| 94 | +
|
| 95 | +For extensions, the [`dev.containers.defaultExtensions` setting](https://code.visualstudio.com/docs/devcontainers/containers#_always-installed-extensions) allows listing extensions that will always be installed. |
| 96 | +
|
| 97 | +For more general customizations, VSCode allows using a dotfile repository. See the [VSCode documentation](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) for more information. |
| 98 | +
|
| 99 | +## GitHub Codespaces |
| 100 | +
|
| 101 | +[](https://codespaces.new/NVIDIA/cccl?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json) |
| 102 | +
|
| 103 | +One of the benefits of Dev Containers is that they integrate natively with [GitHub Codespaces](https://github.com/features/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. |
| 104 | +
|
| 105 | +Click the badge above or [click here](https://codespaces.new/NVIDIA/cccl?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json) to get started with CCCL's Dev Containers on Codespaces. This will start the default Dev Container environment. [Click here](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=296416761&skip_quickstart=true) to start a Codespace with a particular environment and hardware configuration as shown: |
| 106 | + |
| 107 | +  |
| 108 | + |
| 109 | +## For Maintainers: The `make_devcontainers.sh` Script |
| 110 | + |
| 111 | +### Overview |
| 112 | + |
| 113 | +[`make_devcontainers.sh`](./make_devcontainers.sh) generates devcontainer configurations for the unique combinations of CUDA Toolkit (CTK) versions and host compilers in [`ci/matrix.yaml`](../ci/matrix.yaml). |
| 114 | + |
| 115 | +### How It Works: |
| 116 | + |
| 117 | +1. Parses the matrix from `ci/matrix.yaml`. |
| 118 | +2. Use the top-level [`.devcontainer/devcontainer.json`](./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. |
| 119 | +3. Place the generated configurations in the `.devcontainer` directory, organizing them into subdirectories following the naming convention `cuda<CTK_VERSION>-<COMPILER_VERSION>`. |
| 120 | + |
| 121 | +For more information, see the `.devcontainer/make_devcontainers.sh --help` message. |
| 122 | + |
| 123 | +**Note**: When adding or updating supported environments, modify `matrix.yaml` and then rerun this script to synchronize the `devcontainer` configurations. |
| 124 | + |
| 125 | +## Quickstart: Using WSL <a name="wsl"></a> |
| 126 | + |
| 127 | +> [!NOTE] |
| 128 | +> _Make sure you have the Nvidia driver installed on your Windows host before moving further_. Type in `nvidia-smi` for verification. |
| 129 | + |
| 130 | +### Install WSL on your Windows host |
| 131 | + |
| 132 | +> [!WARNING] |
| 133 | +> Disclaimer: This guide was developed for WSL 2 on Windows 11. |
| 134 | + |
| 135 | +1. Launch a Windows terminal (_e.g. Powershell_) as an administrator. |
| 136 | + |
| 137 | +2. Install WSL 2 by running: |
| 138 | +```bash |
| 139 | +wsl --install |
| 140 | +``` |
| 141 | +This should probably install Ubuntu distro as a default. |
| 142 | + |
| 143 | +3. Restart your computer and run `wsl -l -v` on a Windows terminal to verify installation. |
| 144 | + |
| 145 | +<h3 id="prereqs"> Install prerequisites and VS Code extensions</h3> |
| 146 | + |
| 147 | +4. Launch your WSL/Ubuntu terminal by running `wsl` in Powershell. |
| 148 | + |
| 149 | +5. Install the [WSL extension](ms-vscode-remote.remote-wsl) on VS Code. |
| 150 | + |
| 151 | + - `Ctrl + Shift + P` and select `WSL: Connect to WSL` (it will prompt you to install the WSL extension). |
| 152 | +
|
| 153 | + - 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). |
| 154 | +
|
| 155 | +6. Install the [Dev Containers extension](ms-vscode-remote.remote-containers) on VS Code. |
| 156 | +
|
| 157 | + - 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. |
| 158 | +
|
| 159 | +7. Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). **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`). |
| 160 | +
|
| 161 | +8. Open `/etc/docker/daemon.json` from within your WSL system (if the file does not exist, create it) and add the following: |
| 162 | +
|
| 163 | +```json |
| 164 | +{ |
| 165 | + "runtimes": { |
| 166 | + "nvidia": { |
| 167 | + "path": "nvidia-container-runtime", |
| 168 | + "runtimeArgs": [] |
| 169 | + } |
| 170 | + } |
| 171 | +} |
| 172 | +``` |
| 173 | +
|
| 174 | +then run `sudo systemctl restart docker.service`. |
| 175 | +
|
| 176 | +--- |
| 177 | +### Build CCCL in WSL using Dev Containers |
| 178 | +
|
| 179 | +9. Still on your WSL terminal run `git clone https://github.com/NVIDIA/cccl.git` |
| 180 | +
|
| 181 | +
|
| 182 | +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). |
| 183 | +
|
| 184 | +11. If prompted, choose `Reopen in Container`. |
| 185 | +
|
| 186 | + - If you are not prompted just type `Ctrl + Shift + P` and `Dev Containers: Open Folder in Container ...`. |
| 187 | +
|
| 188 | +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](#prereqs) to be followed in a precise order. |
| 189 | +
|
| 190 | +From that point on, the guide aligns with our [existing Dev Containers native Linux guide](https://github.com/NVIDIA/cccl/blob/main/.devcontainer/README.md) with just one minor potential alteration: |
| 191 | +
|
| 192 | +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. |
| 193 | +
|
| 194 | +> Failed opening a web browser at https://github.com/login/device |
| 195 | + exec: "xdg-open,x-www-browser,www-browser,wslview": executable file not found in $PATH |
| 196 | + Please try entering the URL in your browser manually |
| 197 | +
|
| 198 | +In that case type in the address manually in your web browser https://github.com/login/device and fill in the one-time code. |
0 commit comments