diff --git a/.devcontainer/README.md b/.devcontainer/README.md index e0a1d20be7c..93eaa409c81 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1,11 +1,11 @@ > **Note** -> The instructions in this README are specific to Linux development environments. Instructions for Windows is coming soon! +> The instructions in this README are specific to Linux development environments. Instructions for Windows are coming soon! [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/NVIDIA/cccl?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json) # CCCL Dev Containers -To ensure consistency and ease of setup, CCCL uses [Development Containers](https://code.visualstudio.com/docs/devcontainers/containers) for local development and for CI. This guide covers setup in Visual Studio Code and Docker. +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). ## Quickstart: VSCode (Recommended) @@ -27,7 +27,7 @@ To ensure consistency and ease of setup, CCCL uses [Development Containers](http - 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. - ![Shows "Reopen in Container" in command pallete.](./img/open_in_container_manual.png) + ![Shows "Reopen in Container" in command pallete.](./img/open_in_container_manual.png) 4. Select an environment with the desired CTK and host compiler from the list: @@ -43,11 +43,13 @@ To ensure consistency and ease of setup, CCCL uses [Development Containers](http 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. +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 ![Shows authentication with GitHub to access sccache bucket.](./img/github_auth.png) -Even without this step, `sccache` will utilize a local cache on your filesystem, benefiting local rebuilds. To manually trigger this authentication, execute the `devcontainer-utils-vault-s3-init` script within the container. +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`](https://github.com/rapidsai/devcontainers/blob/branch-23.10/USAGE.md#build-caching-with-sccache). @@ -63,7 +65,7 @@ For more information about the sccache configuration and authentication, see the cd cccl ./.devcontainer/launch.sh --docker ``` - This script starts an interactive shell inside the container with the local `cccl/` directory mirrored. + 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: ```bassh @@ -71,21 +73,31 @@ For more information about the sccache configuration and authentication, see the ``` See `./.devcontainer/launch.sh --help` for more information. -2. Done. +2. Done. See the [contributing guide](../CONTRIBUTING.md#building-and-testing) 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`](./devcontainer.json) serves as the default environment. All `devcontainer.json` files in the `cuda-` sub-directories are derived from this top-level file, just with different base images to for the different CUDA and host compiler versions. +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-` 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`](./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](https://code.visualstudio.com/docs/devcontainers/containers#_always-installed-extensions) allows listing extensions that will always be installed. + +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. ## GitHub Codespaces [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/NVIDIA/cccl?quickstart=1&devcontainer_path=.devcontainer%2Fdevcontainer.json) -Dev Containers integrate natively with [GitHub Codespaces](https://github.com/features/codespaces) that 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 with no other setup required. +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. + +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: -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. + ![Shows configuring a Codespace with a custom environment](../docs/images/codespaces.png) ## For Maintainers: The `make_devcontainers.sh` Script @@ -99,9 +111,6 @@ Click the badge above or [click here](https://codespaces.new/NVIDIA/cccl?quickst 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. 3. Place the generated configurations in the `.devcontainer` directory, organizing them into subdirectories following the naming convention `cuda-`. -### Usage: -```bash -make_devcontainers.sh -``` +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. diff --git a/.devcontainer/launch.sh b/.devcontainer/launch.sh index 7618bd15570..0299e0c175e 100755 --- a/.devcontainer/launch.sh +++ b/.devcontainer/launch.sh @@ -1,5 +1,10 @@ #!/usr/bin/env bash +set -euo pipefail + +# Ensure the script is being executed in the cccl/ root +cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )/.."; + print_help() { echo "Usage: $0 [-c|--cuda ] [-H|--host ] [-d|--docker]" echo "Launch a development container. If no CUDA version or Host compiler are specified," @@ -58,7 +63,13 @@ launch_docker() { DOCKER_IMAGE=$(grep "image" "${path}/devcontainer.json" | sed 's/.*: "\(.*\)",/\1/') echo "Found image: ${DOCKER_IMAGE}" docker pull ${DOCKER_IMAGE} - docker run -it --rm -v $(pwd):/workspace ${DOCKER_IMAGE} /bin/bash + docker run \ + -it --rm \ + --user coder \ + --workdir /home/coder/cccl \ + --mount type=bind,src="$(pwd)",dst='/home/coder/cccl' \ + ${DOCKER_IMAGE} \ + /bin/bash } launch_vscode() { @@ -74,11 +85,10 @@ launch_vscode() { mkdir -p "${tmpdir}" mkdir -p "${tmpdir}/.devcontainer" cp -arL "${path}/devcontainer.json" "${tmpdir}/.devcontainer" - sed -i "s@\\${localWorkspaceFolder}@$(pwd)@g" "${tmpdir}/.devcontainer/devcontainer.json" + sed -i 's@\\${localWorkspaceFolder}@$(pwd)@g' "${tmpdir}/.devcontainer/devcontainer.json" local path="${tmpdir}" local hash="$(echo -n "${path}" | xxd -pu - | tr -d '[:space:]')" local url="vscode://vscode-remote/dev-container+${hash}/home/coder/cccl" - echo "devcontainer URL: ${url}" local launch="" if type open >/dev/null 2>&1; then @@ -88,6 +98,7 @@ launch_vscode() { fi if [ -n "${launch}" ]; then + echo "Launching VSCode Dev Container URL: ${url}" code --new-window "${tmpdir}" exec "${launch}" "${url}" >/dev/null 2>&1 fi @@ -97,7 +108,7 @@ main() { parse_options "$@" # If no CTK/Host compiler are provided, just use the default environment - if [[ -z ${cuda_version} ]] && [[ -z ${host_compiler} ]]; then + if [[ -z ${cuda_version:-} ]] && [[ -z ${host_compiler:-} ]]; then path=".devcontainer" else path=".devcontainer/cuda${cuda_version}-${host_compiler}" @@ -108,7 +119,7 @@ main() { fi fi - if $docker_mode; then + if ${docker_mode:-'false'}; then launch_docker else launch_vscode