docs: start an outline of a description of ambient-run

Sponsored-by: author

4 files changed, 108 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index ea8c4bf..6bae391 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /target
+*.html
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..4c6f9f1
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,9 @@
+.SUFFIXES: .subplot .html
+
+.subplot.html:
+	subplot docgen $< -o $@
+
+all: ambient-run.html
+
+ambient-run.html: ambient-run.subplot ambient-run.md
+
diff --git a/ambient-run.md b/ambient-run.md
new file mode 100644
index 0000000..bcf9514
--- /dev/null
+++ b/ambient-run.md
@@ -0,0 +1,93 @@
+# Introduction
+
+`ambient-run` runs continuous integration build locally. It creates a
+virtual machine for each build. The VM has no network access, for
+safety, security, and control. While `ambient-run` is meant to be a
+usable tool on its own, it's also acts as a base component for a full
+CI system. However, the full CI system is outside the scope of this
+documents, which only considers `ambient-run` as a standalone tool.
+
+The build VM contains all the tools needed for the build, and gets all
+the source code and all the dependencies via virtual hard drives. The
+build writes any artifacts is produces to another virtual hard drives.
+Yet another virtual hard drive acts as a cache between builds, to
+allow for incremental builds.
+
+~~~dot
+digraph "ambient-run" {
+    src [label="source \n code" shape=folder]
+    deps [label="dependencies" shape=folder]
+    cache [label="cache" shape=folder]
+    artifact [label="build \n artifacts" shape=folder]
+    VM [label="build \n VM" shape=box3d]
+    log [label="build log" shape=note]
+
+    src -> VM
+    deps -> VM
+    cache -> VM
+    VM -> cache
+    VM -> artifact
+    VM -> log
+}
+~~~
+
+## Example
+
+FIXME: This section will have an example of how to use `ambient-run`.
+
+# Requirements and acceptance criteria
+
+FIXME: This chapter will enumerate all requirements for `ambient-run`,
+as acceptance criteria, using Subplot scenarios to document how to
+verify the software meets the requirements.
+
+## Configuration handling
+
+### Show per-user configuration
+### Show per-project configuration
+### Show per-build configuration
+
+## Building with ambient-run
+
+### Smoke test build works
+### Build is given dependencies
+### Cache is persistent between builds
+### Build gets the resources is demands
+
+## Errors during build
+### Build produces too large an artifact
+### Build produces too large a cache
+### Build demands too many CPUs
+### Build demands too much RAM
+### Build takes too long
+
+# Architecture of `ambient-run`
+
+## Overview
+
+FIXME: This section gives the very high level view of how
+`ambient-run` works: the build VM, the inputs, the cache, the artifact
+output, and how the VM and the outside world interact. It also
+describes that there is per-user and per-project and per-build
+configuration.
+
+## Per-user configuration
+
+FIXME: This section describes the configuration the user sets that
+applies to all use of `ambient-run`.
+
+## Per-project configuration
+
+FIXME: This section describes the configuration that applies to all
+builds of a project.
+
+## Per-build configuration
+
+FIXME: This section describes the configuration for one specific
+build, i.e., one run of `ambient-run`.
+
+## Requirements for the build VM
+
+FIXME: This section describes what `ambient-run` expects of the VM to
+do, what inputs it gets, what outputs it produces, and how it gets the
+per-build instructions.
diff --git a/ambient-run.subplot b/ambient-run.subplot
new file mode 100644
index 0000000..8bf4a66
--- /dev/null
+++ b/ambient-run.subplot
@@ -0,0 +1,5 @@
+title: ambient-run architecture and requirements
+authors:
+  - Lars Wirzenius
+markdowns:
+  - ambient-run.md