initial checkin of mdbp

Proof-of-concept status. Some things work.

1 files changed, 65 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..603d157
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+mdbp
+====
+
+A machine-friendly abstraction of build environments such as `sbuild` or
+`pbuilder`. Primarily, it is an API. To make it useful, it also carries a
+couple of implementations henceforth called backends. Each backend is supplied
+by its own command.
+
+Usage
+-----
+
+To use it, create a JSON file describing the build you intend to perform. There
+is a schema describing the available parameters in `mdbp/build_schema.json`. An
+example build request could be:
+
+    {
+      "input": {"dscpath": "./hello_2.10-2.dsc"},
+      "distribution": "unstable",
+      "output": {"directory": "out"}
+    }
+
+The output directory `out` is supposed to be an empty directory. Then run one
+of the backends `mdbp-BACKEND [BACKENDOPTIONS] REQUEST.json`. The process
+blocks until the build has finished and its return code signifies success or
+failure of the operation. Usage of unsupported parameters of the particular
+backend result in a failure of the operation as a whole.
+
+When to use mdbp?
+-----------------
+
+The target audience performs many builds in a mechanical way. Typically, a
+higher level application needs to perform Debian package builds. Multiple users
+of such an application may prefer different backends.
+
+When not to use mdbp?
+---------------------
+
+Detailed customization and interaction are non-goals. If you need to spawn an
+interactive shell during a failed build, using the underlying implementation is
+better suited.
+
+mdbp-sbuild
+-----------
+
+This backend uses `sbuild` to perform the actual build. It expects that
+`sbuild` is set up and the user running the build has permission to do so. It
+has no backend-specific options.
+
+mdbp-pbuilder
+-------------
+
+This backend uses `pbuilder` to perform the actual build. Unless run as root,
+it performs the build via `sudo`. It assumes that suitable tarballs exist for.
+For distributions `unstable` and `sid`, it'll use the predefined one and for
+any other it'll look for a `<distribution>-base.tgz` or `<distribution>.tgz` in
+`/var/cache/pbuilder`. It has no backend-specific options.
+
+mdbp-mmdebstrap
+---------------
+
+This backend bootstraps a temporary chroot in a user namespace and performs the
+build within. As such it requires working user namespaces including a subuid
+allocation and the suid tool `newuidmap`. Unlike other backends, it does not
+need a chroot or base to be set up before. Given that there is no external
+state, it allows supplying the mirror to be used via the `--mirror` option.