Add basic overview files

1 files changed, 71 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 00000000..c14269aa
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,71 @@
+# Installing the `just` binary
+
+## Building `just` using an older version of `just`
+
+```
+CONF=$(./bin/just-mr.py -C etc/repos.json setup just)
+just -C $CONF build
+```
+
+## Bootstrapping `just`
+
+It is also possible to build `just` without having an older binary,
+using the `bin/boostrap.py` script.
+
+### Bootstrapping compiling the dependencies from scratch
+
+If using bundled dependencies is acceptable, the only thing required
+are a C++20 compiler with the libraries required by the language
+standard and a Python3 interpreter. If you also want the bootstrap
+script to download the dependencies itself, `wget` is required as well.
+
+In this case, the command is simply
+```
+ptyhon3 ./bin/bootstrap.py
+```
+
+The script also takes optionally the following positional arguments (in
+the given order, i.e., specifying one argument requires the ones
+before to be present as well).
+- The directory of the source location (defaulting to the current
+  working directory). Specifying that directory allows calling the
+  script from a different location. It should be noted that the
+  script is written in such a way that the source is not modified.
+- The scratch directory (defaulting to python's `tempfile.mkdtemp()`).
+  The script assumes it can use that directory entirely on its own
+  with no other processes interfering. The bootstraped binary has
+  path `out/bin/just` relative to that direcotry.
+- A directory where (some of) the archives of the dependecies
+  are downloaded ahead of time (defaulting to `.distfiles` in the
+  user's home directory). Whenever an archive is needed, it is
+  first checked if a file with the basename of the URL exists in
+  this directory and has the expected blob id (computed the same
+  way as `git` does). Only if this is not the case, fetching from
+  the network is attempted.
+
+In any case, the resulting binary is selfcontained and can be moved
+to an appropriate location in `PATH`.
+
+### Bootstrapping against preinstalled dependencies (package building)
+
+The main task is to ensure all the dependencies are available at
+sufficiently compatible versions. The full list of dependencies
+can be found in `etc/repos.json`. This file also specifies, in
+the `"local_path"` attribute of `"local_bootstrap"`, the location
+relative to `LOCALBASE` (typically `/usr` or `/usr/local`) that
+is taken as root for the logical respository of that dependency.
+If your distribution prefers to install each package in a separate
+directory, you can always take `/` as `LOCALBASE` and adapt these
+paths accordingly. The instructions on how to link those dependencies
+are stored in the targets files in `etc/import.prebuilt`. Depending
+on the packaging, the linking flags might need adaption as well.
+
+The build command is the same (with the same positional arguments),
+however with the environment variable `PACKAGE` being present
+and `LOCALBASE` set accordingly. As package building requires a
+predictable location on where to pick up the resulting binary, you
+almost certainly want to set the scratch directory.
+
+```
+env PACKAGE=YES LOCALBASE=/usr python3 ${WRKSRC}/bin/bootstrap.py ${WRKSRC} ${WRKDIR}/just-work
+```