1Build modes
2===========
3
4.. _Bazel build settings: https://docs.bazel.build/versions/master/skylark/config.html#using-build-settings
5.. _Bazel configuration transitions: https://docs.bazel.build/versions/master/skylark/lib/transition.html
6.. _Bazel platform: https://docs.bazel.build/versions/master/platforms.html
7
8.. _go_library: /docs/go/core/rules.md#go_library
9.. _go_binary: /docs/go/core/rules.md#go_binary
10.. _go_test: /docs/go/core/rules.md#go_test
11.. _toolchain: toolchains.rst#the-toolchain-object
12
13.. _config_setting: https://docs.bazel.build/versions/master/be/general.html#config_setting
14.. _platform: https://docs.bazel.build/versions/master/be/platform.html#platform
15.. _select: https://docs.bazel.build/versions/master/be/functions.html#select
16
17.. role:: param(kbd)
18.. role:: type(emphasis)
19.. role:: value(code)
20
21.. contents:: :depth: 2
22
23Overview
24--------
25
26The Go toolchain can be configured to build targets in different modes using
27`Bazel build settings`_ specified on the command line or by using attributes
28specified on individual `go_binary`_ or `go_test`_ targets. For example, tests
29may be run in race mode with the command line flag
30``--@io_bazel_rules_go//go/config:race`` or by setting ``race = "on"`` on the
31individual test targets.
32
33Similarly, the Go toolchain can be made to cross-compile binaries for a specific
34platform by setting the ``--platforms`` command line flag or by setting the
35``goos`` and ``goarch`` attributes of the binary target. For example, a binary
36could be built for ``linux`` / ``arm64`` using the command line flag
37``--platforms=@io_bazel_rules_go//go/toolchain:linux_arm64`` or by setting
38``goos = "linux"`` and ``goarch = "arm64"``.
39
40Build settings
41--------------
42
43The build settings below are defined in the package
44``@io_bazel_rules_go//go/config``. They can all be set on the command line
45or using `Bazel configuration transitions`_.
46
47+-------------------+----------------+-----------------------------------------+
48| **Name** | **Type** | **Default value** |
49+-------------------+---------------------+------------------------------------+
50| :param:`static` | :type:`bool` | :value:`false` |
51+-------------------+---------------------+------------------------------------+
52| Statically links the target binary. May not always work since parts of the |
53| standard library and other C dependencies won't tolerate static linking. |
54| Works best with ``pure`` set as well. |
55+-------------------+---------------------+------------------------------------+
56| :param:`race` | :type:`bool` | :value:`false` |
57+-------------------+---------------------+------------------------------------+
58| Instruments the binary for race detection. Programs will panic when a data |
59| race is detected. Requires cgo. Mutually exclusive with ``msan``. |
60+-------------------+---------------------+------------------------------------+
61| :param:`msan` | :type:`bool` | :value:`false` |
62+-------------------+---------------------+------------------------------------+
63| Instruments the binary for memory sanitization. Requires cgo. Mutually |
64| exclusive with ``race``. |
65+-------------------+---------------------+------------------------------------+
66| :param:`pure` | :type:`bool` | :value:`false` |
67+-------------------+---------------------+------------------------------------+
68| Disables cgo, even when a C/C++ toolchain is configured (similar to setting |
69| ``CGO_ENABLED=0``). Packages that contain cgo code may still be built, but |
70| the cgo code will be filtered out, and the ``cgo`` build tag will be false. |
71+-------------------+---------------------+------------------------------------+
72| :param:`debug` | :type:`bool` | :value:`false` |
73+-------------------+---------------------+------------------------------------+
74| Includes debugging information in compiled packages (using the ``-N`` and |
75| ``-l`` flags). This is always true with ``-c dbg``. |
76+-------------------+---------------------+------------------------------------+
77| :param:`gotags` | :type:`string_list` | :value:`[]` |
78+-------------------+---------------------+------------------------------------+
79| Controls which build tags are enabled when evaluating build constraints in |
80| source files. Useful for conditional compilation. |
81+-------------------+---------------------+------------------------------------+
82| :param:`linkmode` | :type:`string` | :value:`"normal"` |
83+-------------------+---------------------+------------------------------------+
84| Determines how the Go binary is built and linked. Similar to ``-buildmode``. |
85| Must be one of ``"normal"``, ``"shared"``, ``"pie"``, ``"plugin"``, |
86| ``"c-shared"``, ``"c-archive"``. |
87+-------------------+---------------------+------------------------------------+
88
89Platforms
90---------
91
92You can define a `Bazel platform`_ using the native `platform`_ rule. A platform
93is essentially a list of facts (constraint values) about a target platform.
94rules_go defines a ``platform`` for each configuration the Go toolchain supports
95in ``@io_bazel_rules_go//go/toolchain``. There are also `config_setting`_ targets
96in ``@io_bazel_rules_go//go/platform`` that can be used to pick platform-specific
97sources or dependencies using `select`_.
98
99You can specify a target platform using the ``--platforms`` command line flag.
100Bazel will automatically select a registered toolchain compatible with the
101target platform (rules_go registers toolchains for all supported platforms).
102For example, you could build for Linux / arm64 with the flag
103``--platforms=@io_bazel_rules_go//go/toolchain:linux_arm64``.
104
105You can set the ``goos`` and ``goarch`` attributes on an individual
106`go_binary`_ or `go_test`_ rule to build a binary for a specific platform.
107This sets the ``--platforms`` flag via `Bazel configuration transitions`_.
108
109
110Examples
111--------
112
113Building pure go binaries
114~~~~~~~~~~~~~~~~~~~~~~~~~
115
116You can switch the default binaries to non cgo using
117
118.. code:: bash
119 bazel build --@io_bazel_rules_go//go/config:pure //:my_binary
120You can build pure go binaries by setting those attributes on a binary.
121
122.. code:: bzl
123
124 go_binary(
125 name = "foo",
126 srcs = ["foo.go"],
127 pure = "on",
128 )
129
130
131Building static binaries
132~~~~~~~~~~~~~~~~~~~~~~~~
133
134| Note that static linking does not work on darwin.
135
136You can switch the default binaries to statically linked binaries using
137
138.. code:: bash
139 bazel build --@io_bazel_rules_go//go/config:static //:my_binary
140You can build static go binaries by setting those attributes on a binary.
141If you want it to be fully static (no libc), you should also specify pure.
142
143.. code:: bzl
144
145 go_binary(
146 name = "foo",
147 srcs = ["foo.go"],
148 static = "on",
149 )
150
151
152Using the race detector
153~~~~~~~~~~~~~~~~~~~~~~~
154
155You can switch the default binaries to race detection mode, and thus also switch
156the mode of tests by using
157
158.. code::
159
160 bazel test --@io_bazel_rules_go//go/config:race //...
161
162Alternatively, you can activate race detection for specific tests.
163
164.. code::
165
166 go_test(
167 name = "go_default_test",
168 srcs = ["lib_test.go"],
169 embed = [":go_default_library"],
170 race = "on",
171 )
View as plain text