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 --make $(MAKE)

scripts/serve_header/README.md

@@ -0,0 +1,85 @@
+serve_header.py
+===============
+
+Serves the `single_include/nlohmann/json.hpp` header file over HTTP(S).
+
+The header file is automatically amalgamated on demand.
+
+![serve_header.py demo](https://user-images.githubusercontent.com/320854/165481390-d65a5180-00d3-443b-b2f1-ea227316309f.png)
+
+## 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
+    ```
+    (see `scripts/serve_header/requirements.txt`)
+
+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 homed in.
+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 goal of supporting multiple project roots or working trees at the same time.
+The recommended folder structure is shown below but `serve_header.py` can work with other structures as well, including a nested hierarchy.
+```
+json/
+├── develop/   ⮜ the main git checkout
+├── feature1/
+├── feature2/    any number of additional
+├── feature3/  ⮜ working trees (e.g., 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 `serve_header.py` is homed in:
+```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.

scripts/serve_header/requirements.txt

@@ -0,0 +1,2 @@
+PyYAML==6.0
+watchdog==2.1.7