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