1# Datawire build-aux Introduction
2
3build-aux is a collection of Makefile `.mk` snippets (and associated
4utilities). Each of the `.mk` snippets is written to be as
5independent from the others as possible, but integrate well by
6following common conventions. You may pick-and-choose which to
7include simply by writing `include build-aux/NAME.mk` in your
8`Makefile`.
9
10Each `.mk` snippet starts with a reference header-comment
11identifying:
12
13 - any eager-evaluated inputs (mostly variables)
14 - any lazy-evaluated inputs (mostly variables)
15 - any outputs (targets, variables)
16 - which targets from other snippets it hooks in to (mostly hooking
17 in to `common.mk` targets)
18
19Eager inputs need to be defined *before* loading the snippet; lazy
20inputs can be defined later. See [`conventions.mk`][./conventions.md]
21for more information on the reference header-comment.
22
23For the most part, you don't need to worry about dependencies between
24`.mk` files; each file will automatically `include` the others it
25depends on. However, if you would like to use an output from one
26snippet as an eager input to another, then you do need to worry about
27include order; if you would like to use `kubernaut-ui.mk` to set
28`KUBECONFIG` for `teleproxy.mk`, then you will need to make sure you
29include `kubernaut-ui.mk` *before* you include `teleproxy.mk`. You
30don't need to worry about including a file twice; this is safe, as
31they all have C-header-style include guards.
32
33## `common.mk`
34
35Most (but not all) of the snippets include `common.mk`, which
36
37 1. Configures Make to use sane settings (since the default settings
38 are set for historical compatibility, not the "right thing").
39
40 2. Defines several `$(call …)`-able helper functions, like
41 `joinlist`, `path.trimprefix`, or `quote.shell`. See
42 [`common.mk`](../common.mk) itself for the full list, and
43 documentation on how to use them.
44
45 3. Declares several utility variables:
46 - `GOOS`, `GOARCH`: Operating system name, and CPU architecture.
47 `GO` is included in the variable names to indicate that they use
48 the same names as `go env` (as opposed to using `uname
49 -s`/`uname -m` names, or something else).
50 - `NL`: a single newline character, since that's hard to type in Make
51 - `SPACE`: a single space character, since that's hard to type in
52 Make
53
54 4. Declares several high-level common targets, like `make build`,
55 `make clean`, or `make check`. See [`common.mk`](../common.mk)
56 itself for the full list. By defining a list of common
57 user-facing targets, the rest of the snippets can hook in to that
58 and provide a uniform interface. With the exception of `make
59 check` (which is special, see below), your `Makefile` can extend
60 any of these by adding dependencies to the target name. For
61 example, to have `make build` build the `foo` file, you could
62 write:
63
64 build: foo
65
66 or to have `make lint` run the `flake8` Python linter, you could
67 write
68
69 lint: flake8
70 flake8:
71 flake8 mypackage/
72 .PHONY: flake8
73
74 or
75
76 lint:
77 flake8 mypackage/
78
79 The former has the advantage that it allows you to add multiple
80 hooks on to `lint` (so it's the only method that build-aux
81 snippets use), and also allows flake8 to run in parallel with
82 other linters set up by build-aux snippets.
83
84 `make check` is special in how it works. Instead of writing
85
86 check: my-test # WRONG
87
88 you write
89
90 test-suite.tap: my-test.tap # CORRECT
91
92 See [`testing.md`](./testing.md) for information about writing the
93 recipe for `my-test.tap`.
94
95 Because of `make check`'s use of `test-suite.tap`, `common.mk`
96 also goes ahead and has `make clean` run `rm -f test-suite.tap`.
97
98 With the exceptions of `make check` and `make clean`, `common.mk`
99 only provides empty definitions; it is up to your `Makefile`, or
100 other `.mk` snippets to make these rules actually do something.
101
102## `help.mk`
103
104The snippet `help.mk` adds a `make help` target, that display
105information about your project (customizable by setting the
106`help.body` variable from your `Makefile`), and a table of all of the
107`make FOO` targets that Make knows about. Any targets you write in
108your `Makefile` that you think should be visible can be added to this
109listing by writing a magic comment:
110
111 frob: ## Frobnicate the splorks
112
113See [`help.mk`](../help.mk) itself for full documentation.
View as plain text