Initial commit

README.md

@@ -0,0 +1,60 @@
+# Mustbuild
+
+Mustbuild is a friendly fork of
+[Justbuild](https://github.com/just-buildsystem/justbuild). It is is maintained
+as a patch series. This fork introduces extensions that mainly focus on
+improving usability while being fully compatible with existing Justbuild
+projects.
+
+Some of those extensions are:
+
+- [A new preprocessor](./doc/preprocessor.md) that supports [language extensions](./doc/must-lang.md)
+- [Improved target descriptions](./doc/targets.md)
+- [Interactive progress reporting](./doc/progress.md)
+- [Reduced command line output](./doc/verbose.md)
+- [Single binary for all subcommands](./doc/single-binary.md)
+
+## Example
+
+In an empty directory, create a file named `TARGETS` with the following content:
+
+```jsonnet
+{
+  // Target 'helloworld' based on built-in rule 'generic'
+  helloworld: {
+    type: 'generic',
+    cmds: ['echo Hello World > out.txt'],
+    outs: ['out.txt'],
+  },
+}
+```
+
+Build the `helloworld` target and print the output file `out.txt`:
+
+```sh
+$ must build helloworld -P out.txt
+INFO: Requested target is [["@","","","helloworld"],{}]
+INFO: Discovered 1 actions, 0 trees, 0 blobs
+INFO: Processed 1 actions, 0 cache hits.
+INFO: Artifacts built, logical paths are:
+        out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
+Hello World
+```
+
+## Tutorial
+
+The tutorial consists of a set of example projects with extensive descriptions.
+It is recommend to look at these projects in order.
+
+1. [Plain project](./examples/1_plain/README.md)
+2. [Minimal C++ project](./examples/2_cpp_min/README.md)
+3. [Advanced C++ project](./examples/3_cpp_adv/README.md)
+    1. [Adding binary and shell tests](./examples/3a_cpp_adv_tests/README.md)
+    2. [Importing external libraries](./examples/3b_cpp_adv_extern/README.md)
+    3. [Using cross-compilation](./examples/3c_cpp_adv_cross/README.md)
+
+## Installing
+
+Obtain and install Mustbuild from the latest bundled
+[releases](https://github.com/oreiche/mustbuild/releases) or build it from
+source. For more details, please see the [build guide](./doc/building.md).

doc/building.md

@@ -0,0 +1,93 @@
+# How to Build
+
+Mustbuild is maintained as a patch series. To build Mustbuild, you first need to
+generate the sources by applying the [patches](../patches) to the specific
+[Justbuild commit](./justbuild.commit).
+
+## 1. Generate sources
+
+You can generate the sources by running the script `generate_sources.sh`:
+
+```sh
+$ ./generate_sources.sh ./srcs
+Fetching Justbuild archive to ~/.distfiles
+Unpacking sources to ./srcs
+Patching sources
+SUCCESS
+$ cd srcs   # step into the source directory for building
+```
+
+Alternatively, you can also check out the specific [Justbuild
+commit](../justbuild.commit) and apply the [patches](../patches) manually.
+
+## 2. Building using `must` or `just-mr`
+
+Once the sources have been successfully generated, you can build Mustbuild with
+`must`:
+
+```sh
+$ must install must -o ${DESTDIR}
+```
+
+... or with `just-mr`:
+
+```sh
+$ just-mr install must -o ${DESTDIR}
+```
+
+### Build options
+
+Build options are specified via JSON objects, encoded as string arguments:
+
+```sh
+$ must install must -D'{"DEBUG":true}' -o ${DESTDIR}
+```
+
+For the full list of variables supported for building Mustbuild, please see
+[Justbuild's build
+variables](https://github.com/just-buildsystem/justbuild/blob/master/INSTALL.md#building-just-for-other-architectures).
+
+### The `ALL` target
+
+To obtain a full installation with auxiliary tools, man pages, and bash
+completion files, use the target `ALL`.
+
+```sh
+$ must install ALL -o ${DESTDIR}
+```
+
+> Note that `pandoc` needs to be installed. You can set its execution
+> environment by specifying variable `PANDOC_ENV` as a JSON object, e.g.,
+> `-D'{"PANDOC_ENV":{"HOME":"/home/user"}}'`.
+
+## 3. Bootstrapping `must`
+
+In case you have neither `must` nor `just-mr` available, you need to bootstrap
+`must` first:
+
+```sh
+$ ./bin/bootstrap.py ${SRCDIR} ${BUILDDIR}
+```
+
+### Bootstrap options
+
+[Build options](#build-options) to the bootstrap process can be provided by
+specifying them as a serialized JSON object assigned to the environment variable
+`JUST_BUILD_CONF`:
+
+```sh
+$ JUST_BUILD_CONF='{"DEBUG":true}' ./bin/bootstrap.py ${SRCDIR} ${BUILDDIR}
+```
+
+The final target that should be built by the bootstrap process can be specified
+using the variable `BOOTSTRAP_TARGET`. This is particularly useful to directly
+bootstrap the [`ALL` target](#the-all-target) described above:
+
+```sh
+$ BOOTSTRAP_TARGET=ALL ./bin/bootstrap.py ${SRCDIR} ${BUILDDIR}
+```
+
+Additional variables used to achieve *package builds* (linking against system
+libraries) are `PACKAGE`, `LOCALBASE`, and `NON_LOCAL_DEPS`. For more
+information on how to use these variables, see [Justbuild's bootstrapping
+documentation](https://github.com/just-buildsystem/justbuild/blob/master/INSTALL.md#bootstrapping-just).