github.com/bazelbuild/rules_go@v0.47.2-0.20240515105122-e7ddb9ea474e/docs/go/core/defines_and_stamping.md (about)

     1  ## Defines and stamping
     2  
     3  In order to provide build time information to go code without data files, we
     4  support the concept of stamping.
     5  
     6  Stamping asks the linker to substitute the value of a global variable with a
     7  string determined at link time. Stamping only happens when linking a binary, not
     8  when compiling a package. This means that changing a value results only in
     9  re-linking, not re-compilation and thus does not cause cascading changes.
    10  
    11  Link values are set in the `x_defs` attribute of any Go rule. This is a
    12  map of string to string, where keys are the names of variables to substitute,
    13  and values are the string to use. Keys may be names of variables in the package
    14  being compiled, or they may be fully qualified names of variables in another
    15  package.
    16  
    17  These mappings are collected up across the entire transitive dependencies of a
    18  binary. This means you can set a value using `x_defs` in a
    19  `go_library`, and any binary that links that library will be stamped with that
    20  value. You can also override stamp values from libraries using `x_defs`
    21  on the `go_binary` rule if needed. The `--[no]stamp` option controls whether
    22  stamping of workspace variables is enabled.
    23  
    24  The values of the `x_defs` dictionary are subject to
    25  [location expansion](https://bazel.build/reference/be/make-variables#predefined_label_variables).
    26  
    27  **Example**
    28  
    29  Suppose we have a small library that contains the current version.
    30  
    31  ``` go
    32  package version
    33  
    34  var Version = "redacted"
    35  ```
    36  
    37  We can set the version in the `go_library` rule for this library.
    38  
    39  ``` bzl
    40  go_library(
    41      name = "version",
    42      srcs = ["version.go"],
    43      importpath = "example.com/repo/version",
    44      x_defs = {"Version": "0.9"},
    45  )
    46  ```
    47  
    48  Binaries that depend on this library may also set this value.
    49  
    50  ``` bzl
    51  go_binary(
    52      name = "cmd",
    53      srcs = ["main.go"],
    54      deps = ["//version"],
    55      x_defs = {"example.com/repo/version.Version": "0.9"},
    56  )
    57  ```
    58  
    59  ### Stamping with the workspace status script
    60  
    61  You can use values produced by the workspace status command in your link stamp.
    62  To use this functionality, write a script that prints key-value pairs, separated
    63  by spaces, one per line. For example:
    64  
    65  ``` bash
    66  #!/usr/bin/env bash
    67  
    68  echo STABLE_GIT_COMMIT $(git rev-parse HEAD)
    69  ```
    70  
    71  ***Note:*** stamping with keys that bazel designates as "stable" will trigger a
    72  re-link when any stable key changes. Currently, in bazel, stable keys are
    73  `BUILD_EMBED_LABEL`, `BUILD_USER`, `BUILD_HOST` and keys whose names start with
    74  `STABLE_`. Stamping only with keys that are not stable keys will not trigger a
    75  relink.
    76  
    77  You can reference these in `x_defs` using curly braces.
    78  
    79  ``` bzl
    80  go_binary(
    81      name = "cmd",
    82      srcs = ["main.go"],
    83      deps = ["//version"],
    84      x_defs = {"example.com/repo/version.Version": "{STABLE_GIT_COMMIT}"},
    85  )
    86  ```
    87  
    88  You can build using the status script using the `--workspace_status_command`
    89  argument on the command line:
    90  
    91  ``` bash
    92  $ bazel build --stamp --workspace_status_command=./status.sh //:cmd
    93  ```
    94