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 ) 172