Conventions for use in build-aux

Each .mk snippet starts with a reference header-comment of the format:

```make
# Copyright statement.
#
# A sentence or two introducing what this file does.
#
## Section heading ##
#  - type: item
#  - type: item
## Section heading ##
#  - item
#  - item
#
# High-level prose documentation.
```

Always include (at a minimum) these 4 sections, even if their content is (none):

• ## Eager inputs ## (mostly variables) Eager-evaluated inputs that need to be defined before loading the snippet
• ## Lazy inputs ## (mostly variables) Lazy-evaluated inputs can be defined before or after loading the snippet
• ## Outputs ## (targets, variables, et c.)
• ## common.mk targets ##

If there are which targets from snippets other than common.mk that it hooks in to, a section for each of those snippets should exist too.

The most common reason for an input to be eager is if it is listed as a dependency of a target defined in the .mk file.

Bullet points under "Eager inputs", "Lazy inputs", or "Outputs" should be of the format "Type: thing [extra info]", optionally with the ":" aligned between rows. Types currently used are:

• Target(s) (only for use as an output): Indicates that the snippet defines rules to create the specified file(s). Prefer to list each target separately; only use the plural Targets when listing an expression that govers a large range of actual files.
• .PHONY Target(s) (only for use as an output): Like Target, but is declared as .PHONY; a file with that name is never actually created.
• File (only for use as an input): Indicates that this file is parsed by the Makefile snippet. Note that it should not be a file described by a Target, since it needs to be there at Makefile-parse-time.
• Variable: The meaning is obvious.
  • For inputs: If there is a default value, the listing should include ?= value for a possibly pseudo-code or comment value documenting what the default value is.
  • For outputs: The listing should include = value or ?= value for a possibly pseudo-code or comment value documenting what the variable is set to contain. The = should be ?= as appropriate, to document whether it can be overridden by the caller/user.
  • If a ?= variable is listed in "Outputs", consider also listing it in "inputs"; if an input gets a default value set, consider also listing it in "Outputs".
    • NAME in go-mod.mk. It isn't listed as an an input, because it isn't one "in spirit".
    • "Executables" (below) are set with ?=, but don't list them as "inputs".
• Function: (only for use as an output) This is a special case of a Variable that defines a function to be called with $(call funcname,args). Should not be listed as an input; if you depend on a function, just go ahead and include the snippet that defines it.
• Executable (only for use as an output): An "Executable" output is a special-case of both a "Target" output and a "Variable" input/output. An "Executable" output has the following attributes:
  • It is exposed as a variable that stores an absolute path to an executable file (this makes it safe to list as a dependency).
  • That variable can be overridden using an environment variable (that is: it is set with ?=).
  • It is NOT guaranteed to already exist (you may need to depend on it), but a rule to create it is guaranteed be there it it doesn't already exist.
  • Overriding it using an environment variable will not affect the rule to create the standard version, or cleanup rules to remove it; those targets do not obey the environment variable.