...

Text file src/github.com/datawire/ambassador/v2/build-aux/docs/conventions.md

Documentation: github.com/datawire/ambassador/v2/build-aux/docs

     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