1# Datawire build-aux
2
3This is a collection of Makefile snippets (and associated utilities)
4for use in Datawire projects.
5
6It has the following downsides:
7 1. It does not support out-of-tree builds.
8 2. It has no notion of nesting. You cannot `cd` to a sub-directory,
9 run `make`, and have it just build the stuff in that directory.
10 3. It has no notion of nesting. If you want per-directory build
11 descriptions, you'll have to build that functionality yourself, or
12 offload it to a separate build-system, like `go` or `setup.py`.
13 4. Most of the `.mk` snippets have a hard dependency on the `go`
14 program being in `PATH`, even if none of the sources are Go.
15
16If any of those are a bummer, but you still want the "Make snippets in
17a `./build-aux/` folder" concept, consider
18[Autothing](https://git.lukeshu.com/autothing/) (which has the
19downsides that it requires GNU Make 3.82 or above, and is slow).
20
21At Datawire, those are good trade-offs, since:
22 - We're mostly a Python and Go shop (we don't care about #2 or #3,
23 and only care about #4 for Python-only projects).
24 - I've never heard anyone here even mention out-of-tree builds (#1).
25 - We need to support macOS (which still ships GNU Make 3.81, as it's
26 the last GPLv2 version) (so Autothing is ruled out).
27
28## How to use
29
30Add `build-aux.git` as `build-aux/` in the git repository of the
31project that you want to use this from. I recommend that you do this
32using `git subtree`, but `git submodule` is fine too.
33
34Then, in your Makefile, write `include build-aux/FOO.mk` for each
35common bit of functionality that you want to make use of.
36
37### Using `git-subtree` to manage `./build-aux/`
38
39 - Start using build-aux:
40
41 $ git subtree add --squash --prefix=build-aux git@github.com:datawire/build-aux.git master
42
43 - Update to latest build-aux:
44
45 $ ./build-aux/build-aux-pull
46
47 - Push "vendored" changes upstream to build-aux.git:
48
49 $ ./build-aux/build-aux-push
50
51### Documentation
52
53 - Each `.mk` snippet contains a reference-quality header comment
54 identifying
55 - any "eager" inputs (mostly variables); these must be defined
56 *before* including the `.mk` file.
57 - any "lazy" inputs (mostly variables); these may be defined
58 before or after including the `.mk` file.
59 - any outputs (targets, variables)
60 - which targets from other snippets it hooks in to (mostly hooking
61 in to `common.mk` targets)
62 - [`docs/intro.md`](./docs/intro.md) is an introduction to
63 big-picture ideas in `*.mk` snippets.
64 - [`docs/golang.md`](./docs/golang.md) discusses support for building
65 software written in Go.
66 - [`docs/testing.md`](./docs/testing.md) discusses adding tests to
67 `make check`.
68 - [`HACKING.md`](./HACKING.md) has guidelines for contributing to
69 `build-aux.git`.
View as plain text