1 files changed, 122 insertions, 0 deletions
diff --git a/scripts/crossbuild/README.md b/scripts/crossbuild/README.md
new file mode 100644
index 0000000..0bcc2c4
--- /dev/null
+++ b/scripts/crossbuild/README.md
@@ -0,0 +1,122 @@
+# Crossbuild
+
+## Summary
+
+The "crossbuild" system is a way to build FreeRADIUS for multiple
+different operating systems, using Docker.
+
+The primary purpose is for developers to easily test FreeRADIUS on
+different systems.
+
+
+## Common Usage
+
+The systems supported can be listed with
+
+    make crossbuild.info
+
+A reminder of the make targets may be seen with
+
+    make crossbuild.help
+
+To make all the known systems (this may take quite a while, at
+least on the first run):
+
+    make crossbuild
+
+or for the most common systems (Debian, Ubuntu, CentOS):
+
+    make crossbuild.common
+
+
+## General operation
+
+The system works by building and then starting up Docker
+containers for the systems. When a build is triggered (either
+generally, as above, or for a specific OS) the current git commits
+are copied into the image and then `make test` run.
+
+The Docker containers are left running, and may be stopped with
+
+    make crossbuild.down
+
+The system tries to be as efficient as possible, so will not
+rebuild from scratch every time.
+
+
+## Global make targets
+
+The following targets will operate on the crossbuild system
+globally, or on all images (unless otherwise stated):
+
+
+### `make crossbuild`
+
+Create all docker images (if required), start them, build and test
+FreeRADIUS.
+
+
+### `make crossbuild.common`
+
+As `make crossbuild`, but only build and test the most common
+systems.
+
+
+### `make crossbuild.info`
+
+List all systems, together with the expected state. See
+`crossbuild.reset`.
+
+
+### `make crossbuild.down`
+
+Stop all containers.
+
+
+### `make crossbuild.reset`
+
+If containers are stopped or started outside Docker, crossbuild
+may get confused. This will clear the internal state which should
+try and start everything from be beginning again.
+
+
+### `make crossbuild.clean`
+
+Bring down all containers, clear state. This is a general "tidy
+up".
+
+
+### `make crossbuild.wipe`
+
+Don't just stop, but destroy all crossbuild docker images. This
+will mean they need to be recreated again upon next use.
+
+
+## Per-image make targets
+
+The following make targets may be used on a per-image basis:
+
+ * `make crossbuild.IMAGE`:         build and test image
+ * `make crossbuild.IMAGE.log`:     show latest build log
+ * `make crossbuild.IMAGE.up`:      start container
+ * `make crossbuild.IMAGE.down`:    stop container
+ * `make crossbuild.IMAGE.sh`:      shell in container
+ * `make crossbuild.IMAGE.refresh`: push latest commits into container
+ * `make crossbuild.IMAGE.clean`:   stop container and tidy up
+ * `make crossbuild.IMAGE.wipe`:    remove Docker image
+
+For example, `make crossbuild.debian10` to create, build and test
+FreeRADIUS on Debian 10. `make crossbuild.debian10.down` will then
+stop the container.
+
+
+## Docker image and container names
+
+Docker images will be created with names in the form:
+
+    freeradius-build/debian10
+
+whil containers will have names like:
+
+    fr-crossbuild-debian10
+