From dbb28e73dce8a0069a1f7be62d30f899ffd7e155 Mon Sep 17 00:00:00 2001
From: Alex Allmont <alex.allmont@dtc.ox.ac.uk>
Date: Sat, 9 Nov 2024 20:21:56 +0000
Subject: [PATCH] feat: Add VSCode devcontainer (#148)

- Installs python, git, gdb for dev environment
- Python venv created in /tools/venv (in container, not on local machine) with build requirements pre-installed.
- vcpkg cloned and setup in /tools/vcpkg. Note the FIXME on VCPKG_FORCE_SYSTEM_BINARIES added to get working on MacOS running a Linux container, as it may need to be made conditional on platform.
- PYTHONPATH and PATH setup so integrated terminal works.
- First draft of developer guide README.md.
- devcontainer.json has cmake and python settings as in Dockerfile
---
 .devcontainer/Dockerfile        | 47 +++++++++++++++++++++++++++++++++
 .devcontainer/README.md         | 31 ++++++++++++++++++++++
 .devcontainer/devcontainer.json | 39 +++++++++++++++++++++++++++
 3 files changed, 117 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/README.md
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000..8a0e1705
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,47 @@
+FROM ubuntu:22.04
+
+# Install python
+RUN apt-get update
+RUN apt-get install -y \
+    python3 \
+    python3-venv \
+    python3-pip
+
+# Dev tools require an additional update
+RUN apt-get update
+RUN apt-get install -y \
+    git \
+    gdb \
+    curl \
+    zip \
+    unzip \
+    tar \
+    autoconf \
+    libtool \
+    libtool-bin \
+    pkg-config
+
+WORKDIR /tools
+
+# Create new venv at container root and install libs
+RUN python3 -m venv /tools/venv
+ENV PATH /tools/venv/bin:$PATH
+RUN pip install --upgrade pip setuptools wheel
+RUN pip install \
+    cmake \
+    ninja \
+    pybind11 \
+    numpy \
+    pytest \
+    pytest-cov
+
+# FIXME make conditional on arm, s390x, ppc64le and riscv
+ENV VCPKG_FORCE_SYSTEM_BINARIES=1
+
+# Install vcpkg in checkout location
+RUN git clone https://github.com/Microsoft/vcpkg.git /tools/vcpkg
+RUN /tools/vcpkg/bootstrap-vcpkg.sh
+ENV PATH /tools/vcpkg:$PATH
+
+# This is required to be able to run pytest in the VSCode terminal
+ENV PYTHONPATH=.
\ No newline at end of file
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
new file mode 100644
index 00000000..019f933c
--- /dev/null
+++ b/.devcontainer/README.md
@@ -0,0 +1,31 @@
+# Build and debug in VSCode devcontainer
+
+The `.devcontainer/` folder provides a consistent build and debug environment that can be run in VSCode locally or in GitHub Codespaces remotely.
+
+## Opening devcontainer locally
+
+When you open the cloned RoughPy folder in VSCode, accept the popup to open in a Dev Container or run the editor command `Dev Containers: Reopen in Dev Container`.
+
+VSCode will restart inside a container that will have mapped your checkout folder to `/workspaces/<dirname>`, so be mindful that editing files is affecting this folder on your machine.
+
+The devcontainer `Dockerfile` sets up a root `/tools` folder that contains a `venv` with build dependencies pre-installed, and a clone of `vcpkg`; both of which are added to `$PATH`.
+
+## Building, testing and debugging
+
+Run the editor command `CMake: Select Configure Preset` and select `Debug Develop` to compile with debug symbols. Then run `CMake: build`.
+
+The devcontainer automatically installs the pytest and CTest extension, so after building you can launch any of the tests from the VSCode test explorer panel. Alternatively, you can run directly `pytest` directly from the integrated terminal.
+
+VSCode loads debug scenarios from `.vscode/launch.json`. However, developers frequently need to edit this file with changes that should not be committed, so here they are stored in `example_launch.json` which must be manually copied over with:
+
+```sh
+    cp .vscode/example_launch.json .vscode/launch.json
+```
+
+Select a debug scenario in the Run and Debug panel, add a breakpoint on the code to stop on, and launch with F5.
+
+The three example scenarios are:
+
+- `debugpy pytest` - Debug a specific `pytest` unit test in a python debugger.
+- `gdb pytest` - Start a python test and debug any underlying C++.
+- `gdb gtest` - Debug a specific GTest unit test in a C++ debugger.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..3a42f3c5
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,39 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/cpp
+{
+    "name": "RoughPy",
+
+    "build": {
+        "dockerfile": "Dockerfile"
+    },
+
+    "customizations": {
+        "vscode":{
+            "extensions": [
+                "ms-python.debugpy",
+                "ms-python.python",
+                "ms-python.vscode-pylance",
+                "ms-vscode.cmake-tools",
+                "ms-vscode.cpptools",
+                "ms-vscode.cpptools-extension-pack"
+            ],
+            "settings": {
+                "python.defaultInterpreterPath": "/tools/venv/bin/python",
+                "python.languageServer": "Pylance",
+                "python.testing.pytestEnabled": true,
+                "cmake.cmakePath": "/tools/venv/bin/cmake",
+                "cmake.configureArgs": [
+                    "-DCMAKE_MAKE_PROGRAM=/tools/venv/bin/ninja",
+                    "-DCMAKE_TOOLCHAIN_FILE=/tools/vcpkg/scripts/buildsystems/vcpkg.cmake",
+                    "-DROUGHPY_BUILD_TESTS=ON",
+                    "-DROUGHPY_BUILD_PYLIB_INPLACE=ON"
+                ]
+            }
+        }
+    },
+
+    // Enable debugging in container
+    "capAdd": [
+        "SYS_PTRACE"
+    ]
+}