From 873fdc47679b9784d8d98376dd3448492db5cfb4 Mon Sep 17 00:00:00 2001
From: Shish <shish@shishnet.org>
Date: Thu, 28 Nov 2024 07:35:26 +0000
Subject: [PATCH] Add devcontainer config

(breaking shish/safe down into smaller parts for easier merging)

These configs make it so that one can open the Safe project in a compatible editor (eg vscode) and the IDE will do all the work (eg build, test) in a self-contained container with all the right versions of all the right tools installed. This is particularly useful for Safe, whose build process only runs with specific PHP versions, which may differ from what is installed on the developer's host system.
---
 .devcontainer/Dockerfile        |  6 ++++++
 .devcontainer/build.sh          |  3 +++
 .devcontainer/devcontainer.json | 10 ++++++++++
 .devcontainer/run.sh            |  3 +++
 CONTRIBUTING.md                 | 13 +++++++++++++
 5 files changed, 35 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100755 .devcontainer/build.sh
 create mode 100644 .devcontainer/devcontainer.json
 create mode 100755 .devcontainer/run.sh

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000..e2b482e9
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,6 @@
+FROM debian:stable
+ARG DEBIAN_FRONTEND=noninteractive
+ARG XDEBUG_MODE=coverage
+RUN apt update -y && apt install -y git composer php-cli php-dom php-curl php-xdebug vim
+WORKDIR /app
+CMD cd /app/generator/doc && ./update.sh && cd /app/generator && composer install && php ./safe.php generate && composer cs-fix
diff --git a/.devcontainer/build.sh b/.devcontainer/build.sh
new file mode 100755
index 00000000..f7b640c0
--- /dev/null
+++ b/.devcontainer/build.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+cd $(dirname $0)/../
+docker run --rm -v ${PWD}:/app $(docker build -q -f .devcontainer/Dockerfile .)
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..26b9f0ae
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,10 @@
+{
+	"name": "Safe PHP",
+	"build": {
+		"context": "..",
+		"dockerfile": "./Dockerfile"
+	},
+
+	"workspaceMount": "source=${localWorkspaceFolder},target=/app,type=bind",
+	"workspaceFolder": "/app"
+}
diff --git a/.devcontainer/run.sh b/.devcontainer/run.sh
new file mode 100755
index 00000000..d698c90c
--- /dev/null
+++ b/.devcontainer/run.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+cd $(dirname $0)/../
+docker run --rm -ti -v ${PWD}:/app $(docker build -q . -f .devcontainer/Dockerfile) /bin/bash
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ecb2c1b9..9f9cf3e8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,19 @@
 
 Safe-PHP code is generated automatically from the PHP doc.
 
+## Install dependencies
+
+### With a devcontainer
+
+If you use VSCode or similar, opening the project folder should prompt you to
+re-open the folder inside a docker container with all the relevant tools
+pre-installed.
+
+### Manually
+
+- php8.2+ CLI (with dom and curl modules)
+- composer
+
 ## How to install Safe-PHP development environment
 
 The first step is to download the PHP documentation project locally, using git.