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