Merge branch 'contributor-guide' into contributor-guide-pt2

.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,29 +65,39 @@ 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
     ./.devcontainer/launch.sh --docker --cuda 12.2 --host gcc10
     ```
     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<CTK_VERSION>-<HOST-COMPILER>` 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<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`](./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<CTK_VERSION>-<COMPILER_VERSION>`.
 
-### 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.

.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 <CUDA version>] [-H|--host <Host compiler>] [-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