1# Conventions for use in build-aux
2
3Each `.mk` snippet starts with a reference header-comment of the
4format:
5
6 ```make
7 # Copyright statement.
8 #
9 # A sentence or two introducing what this file does.
10 #
11 ## Section heading ##
12 # - type: item
13 # - type: item
14 ## Section heading ##
15 # - item
16 # - item
17 #
18 # High-level prose documentation.
19 ```
20
21Always include (at a minimum) these 4 sections, even if their content
22is `(none)`:
23
24 - `## Eager inputs ##` (mostly variables) Eager-evaluated inputs that
25 need to be defined *before* loading the snippet
26 - `## Lazy inputs ##` (mostly variables) Lazy-evaluated inputs can be
27 defined before *or* after loading the snippet
28 - `## Outputs ##` (targets, variables, et c.)
29 - `## common.mk targets ##`
30
31If there are which targets from snippets other than `common.mk` that
32it hooks in to, a section for each of those snippets should exist too.
33
34The most common reason for an input to be eager is if it is listed as
35a dependency of a target defined in the `.mk` file.
36
37Bullet points under "Eager inputs", "Lazy inputs", or "Outputs" should
38be of the format "Type: thing [extra info]", optionally with the ":"
39aligned between rows. Types currently used are:
40
41 - `Target(s)` (only for use as an output): Indicates that the snippet
42 defines rules to create the specified file(s). Prefer to list each
43 target separately; only use the plural `Targets` when listing an
44 expression that govers a large range of actual files.
45 - `.PHONY Target(s)` (only for use as an output): Like `Target`, but
46 is declared as `.PHONY`; a file with that name is never actually
47 created.
48 - `File` (only for use as an input): Indicates that this file is
49 parsed by the Makefile snippet. Note that it should not be a file
50 described by a Target, since it needs to be there at
51 Makefile-parse-time.
52 - `Variable`: The meaning is obvious.
53 * For inputs: If there is a default value, the listing should
54 include `?= value` for a possibly pseudo-code or comment `value`
55 documenting what the default value is.
56 * For outputs: The listing should include `= value` or `?= value`
57 for a possibly pseudo-code or comment `value` documenting what
58 the variable is set to contain. The `=` should be `?=` as
59 appropriate, to document whether it can be overridden by the
60 caller/user.
61 * If a `?=` variable is listed in "Outputs", consider also listing
62 it in "inputs"; if an input gets a default value set, consider
63 also listing it in "Outputs".
64 - `NAME` in `go-mod.mk`. It isn't listed as an an input, because
65 it isn't one "in spirit".
66 - "Executables" (below) are set with `?=`, but don't list them as
67 "inputs".
68 - `Function`: (only for use as an output) This is a special case of a
69 Variable that defines a function to be called with `$(call
70 funcname,args)`. Should not be listed as an input; if you depend
71 on a function, just go ahead and include the snippet that defines
72 it.
73 - `Executable` (only for use as an output): An "Executable" output is
74 a special-case of both a "Target" output and a "Variable"
75 input/output. An "Executable" output has the following attributes:
76 * It is exposed as a variable that stores an absolute path to an
77 executable file (this makes it safe to list as a dependency).
78 * That variable can be overridden using an environment variable
79 (that is: it is set with `?=`).
80 * It is NOT guaranteed to already exist (you may need to depend on
81 it), but a rule to create it is guaranteed be there it it doesn't
82 already exist.
83 * Overriding it using an environment variable will not affect the
84 rule to create the standard version, or cleanup rules to remove
85 it; those targets do not obey the environment variable.
View as plain text