Add serve_header.py for rapid testing on Compiler Explorer

.gitignore

@@ -10,7 +10,14 @@
 /.idea
 /cmake-build-*
 
-/.vs
+/.vs/
+/.vscode/
+
+# clangd cache
+/.cache/
+
+# build directories (vscode-cmake-tools, user-defined, ...)
+/build*/
 
 /doc/mkdocs/docs/examples/
 /doc/mkdocs/docs/__pycache__/
@@ -19,3 +26,8 @@
 /doc/docset/JSON_for_Modern_C++.docset/
 /doc/docset/JSON_for_Modern_C++.tgz
 /doc/mkdocs/docs/images/json.gif
+
+# serve_header
+/serve_header.yml
+/localhost.pem
+/localhost-key.pem

Makefile

@@ -251,3 +251,10 @@ update_hedley:
 	$(SED) -i '1s/^/#pragma once\n\n/' include/nlohmann/thirdparty/hedley/hedley.hpp
 	$(SED) -i '1s/^/#pragma once\n\n/' include/nlohmann/thirdparty/hedley/hedley_undef.hpp
 	$(MAKE) amalgamate
+
+##########################################################################
+# serve_header.py
+##########################################################################
+
+serve_header:
+	./scripts/serve_header/serve_header.py

scripts/serve_header/README.md

@@ -0,0 +1,81 @@
+serve_header.py
+===============
+
+Serves the `single_include/nlohmann/json.hpp` header file over HTTP(S).
+
+The header file is automatically amalgamated on demand.
+
+## Prerequisites
+
+> **Note:** All file locations are relative to the project root folder and all commands are assumed to be executed from the same root folder.
+
+1. Make sure these Python packages are installed.
+    ```
+    PyYAML
+    watchdog
+    ```
+
+2. To serve the header over HTTPS (which is required by Compiler Explorer at this time), a certificate is needed.
+   The recommended method for creating a locally-trusted certificate is to use [`mkcert`](https://github.com/FiloSottile/mkcert).
+   - Install the `mkcert` certificate authority into your trust store(s):
+     ```
+     $ mkcert -install
+     ```
+   - Create a certificate for `localhost`:
+     ```
+     $ mkcert localhost
+     ```
+
+## Usage
+
+`serve_header.py` has a builtin default configuration that will serve the header from the project folder it is launched from.
+It expects to find the certificate `localhost.pem` and the private key `localhost-key.pem` in the projects root directory.
+
+To start serving the `json.hpp` header file at `https://localhost:8443/json.hpp`, run this command:
+```
+$ make serve_header
+```
+
+Open [Compiler Explorer](https://godbolt.org/) and try it out:
+```cpp
+#include <https://localhost:8443/json.hpp>
+using namespace nlohmann;
+
+#include <iostream>
+
+int main() {
+    // these macros are dynamically injected into the header file
+    std::cout << JSON_BUILD_TIME << " (" << JSON_BUILD_COUNT << ")\n";
+
+    return 0;
+}
+```
+
+> `serve_header.py` dynamically injects the macros `JSON_BUILD_COUNT` and `JSON_BUILD_TIME` into the served header. By comparing build count or time output from the compiled program with the output from `serve_header.py`, one can be reasonably sure the compiled code uses the expected revision of the header file.
+
+## Configuration
+
+`serve_header.py` will try to read a configuration file `serve_header.yml` and will fallback on builtin defaults, if the file cannot be read.
+An annotated example configuration can be found in `scripts/serve_header/serve_header.yml.example`.
+
+## Serving `json.hpp` from multiple working trees
+
+`serve_header.py` was designed with the following folder structure in mind:
+```
+json/
+├── develop/   ⮜ the main git checkout
+├── feature1/
+├── feature2/    any number of additional
+├── feature3/  ⮜ working trees created
+└── feature4/    with git worktree
+└── feature5/
+```
+
+To serve the header of each working tree at `https://localhost:8443/<worktree>/json.hpp`, a configuration file is needed.
+Create the file `serve_header.yml` in the project folder where `serve_header.py` is launched from:
+```yaml
+root: ..
+```
+By shifting the root folder up one level the headers from all sibling directories will be served.
+
+`serve_header.py` will automatically detect the addition or removal of working trees in the configured root folder.