1# Hacking on build-aux.git
2
3## Misc notes
4
5 - If you have a dependency on another `.mk` file includes, include it
6 with `include $(dir $(lastword $(MAKEFILE_LIST)))common.mk`.
7 - `.PHONY` targets that you wish to be user-visible should have a `##
8 Help text` usage comment. See `help.mk` for more information.
9 - Wrap your `.mk` files in
10
11 ifeq ($(words $(filter $(abspath $(lastword $(MAKEFILE_LIST))),$(abspath $(MAKEFILE_LIST)))),1)
12 …
13 endif
14
15 include guards to make sure they are only included once; similar to
16 how you would with a C header file.
17 - The Make `export` directive *only* affects recipes, and does *not*
18 affect `$(shell …)`. Because of this, you shoud not call `go`
19 inside of `$(shell …)`, as `$GO111MODULE` may not have the correct
20 value.
21 - Make sure to pass `--fail` to `curl` when downloading things;
22 otherwise it will silently save 404 HTML/XML pages.
23 - Don't depend on anything in ./build-aux/bin/ during clean and
24 clobber rules. The `prelude.mk` cleanup might remove it before
25 your cleanup bit runs. For Go programs, `cd` to the program's
26 sourcedirectory, and use `go run .` to run it:
27
28 cd $(dir $(_myfile.mk))bin-go/PROGRAM && GO111MODULE=on go run . ARGS...
29
30 Only tolerate that grossness in your cleanup rules.
31
32## Naming conventions
33
34 - `check` and `check-FOO` are `.PHONY` targets that run tests.
35 - `test-FOO` is an executable program that when run tests FOO.
36 Perhaps the `check-FOO` Make target compiles and runs the
37 `test-FOO` program.
38 - `test` is the POSIX `test(1)` command. Don't use it as a Makefile
39 rule name.
40 - (That is, use "check" as a *verb*, and "test" as a *noun*.)
41 - Internal "private" variables should be named `_snippet-name.VAR`;
42 for example, a variable internal to `k8s.mk` might be named
43 `_k8s.push`.
44
45## Compatibility
46
47 - Everything should work with GNU Make 3.81 AND newer versions.
48 * Avoid Make features introduced in 3.82 or later.
49 * The 3.81→3.82 update changed precedence of pattern rules from
50 "parse-order-based" to "stem-length-based". Be careful that your
51 pattern rules work in BOTH systems.
52 - Requires `go` 1.11 or newer.
53 - Using `--` to separate positional arguments isn't POSIX, but is
54 implemented in `getopt(3)` and `getopt_long(3)` in every major libc
55 (including macOS). Therefore, `--` working is a reasonable base
56 assumption. Known exceptions:
57 * macOS `chmod`
58 - Prefer `curl` to `wget`; macOS ships with `curl`, it doesn't ship
59 with `wget`.
60
61## Style guide
62
63 - See "Naming conventions"..
64 - See [`docs/conventions.md`](./docs/conventions.md).
65 - Place `.PHONY:` immediately *after* the rule definition.
66 - Use pattern rules instead of "old-fashioned suffix rules" (as the
67 GNU Make manual refers to them).
View as plain text