diff options
| -rw-r--r-- | INSTALL.md | 71 | ||||
| -rw-r--r-- | README.md | 34 |
2 files changed, 105 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 +``` diff --git a/README.md b/README.md new file mode 100644 index 00000000..9883a75d --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# Justbuild + +Justbuild is a generic build system supporting multi-repository +builds. A pecularity of the tool is the separation between global +names and physical location on the one hand, and logical paths +used for actions and installation (sometimes referred to as +"staging"). Language-specific information to translate high-level +concepts (libraries, binaries) into individual compile action is +taken from user-defined rules described by functional expressions. + +## Getting Started + +* The most simple way to build the `just` binary from scratch + is `python3 ./bin/bootstrap.py`. For more details see the + [installation guide](INSTALL.md). + +* Tutorial + - [Hello World](doc/tutorial/hello-world.org) + - [Third party dependencies](doc/tutorial/third-party-software.org) + - [Tests](doc/tutorial/tests.org) + - [Using protobuf](doc/tutorial/proto.org) + +## Documentation + +- [Overview](doc/concepts/overview.org) +- [Build Configurations](doc/concepts/configuration.org) +- [Multi-Repository Builds](doc/concepts/multi-repo.org) +- [Expression Language](doc/concepts/expressions.org) +- [Built-in Rules](doc/concepts/built-in-rules.org) +- [User-Defined Rules](doc/concepts/rules.org) +- [Documentation Strings](doc/concepts/doc-strings.org) +- [Cache Pragma and Testing](doc/concepts/cache-pragma.org) +- [Anonymous Targets](doc/concepts/anonymous-targets.org) +- [Target-Level Caching](doc/concepts/target-cache.org) |