github.com/ajguerrer/rules_go@v0.20.3/go/modes.rst (about) 1 Build modes 2 =========== 3 4 .. _go_library: core.rst#go_library 5 .. _go_binary: core.rst#go_binary 6 .. _go_test: core.rst#go_test 7 .. _toolchain: toolchains.rst#the-toolchain-object 8 9 .. contents:: :depth: 2 10 11 Overview 12 -------- 13 14 There are a few modes in which the core go rules can be run, and the selection 15 mechanism depends on the nature of the variation. 16 17 Build modes can be selected either on the command line, or controlled on the 18 go_binary and go_test rules using `mode attributes`_. 19 20 The `command line`_ sets defaults that affect all rules, but explicit settings on 21 a rule always override the command line. Not all build modes can be controlled 22 in both places. 23 24 25 Command line 26 ~~~~~~~~~~~~ 27 28 On the command line, there are a few mechanisms that influence the build mode. 29 30 +---------------------+------------------------------------------------------------------+ 31 | --features | Controls race_, static_, msan_ and pure_, see features_ | 32 +---------------------+------------------------------------------------------------------+ 33 | --cpu | Controls GOOS_ GOARCH_, also forces pure_ for cross compilation | 34 +---------------------+------------------------------------------------------------------+ 35 | --compilation_mode | Controls debug_ and strip_ | 36 +---------------------+------------------------------------------------------------------+ 37 | --strip | Controls strip_ | 38 +---------------------+------------------------------------------------------------------+ 39 40 41 Features 42 ~~~~~~~~ 43 44 Features are normally off, unless you select them with :code:`--features=featurename` on the bazel 45 command line. Features are generic tags that affect *all* rules, not just the ones you specify or 46 even just the go ones, and any feature can be interpreted by any rule. There is also no protections 47 that two different rules will not intepret the same feature in very different ways, and no way for 48 rule authors to protect against that, so it is up to the user when specifying a feature on the 49 command line to know what it's affects will be on all the rules in their build. 50 51 Available features that affect the go rules are: 52 53 * race_ 54 * static_ 55 * msan_ 56 * pure_ 57 58 Mode attributes 59 ~~~~~~~~~~~~~~~ 60 61 Only rules that link accept build mode controlling attributes (go_binary_ and go_test_, not go_library_). 62 The entire transitive set of libraries that a leaf depends on are built in the mode specified by 63 the binary rule. The compiled libraries are distinct and multiple modes can be built in a single pass, 64 but are shared between leaves building in the same mode. 65 66 Currently only static_, pure_, goos_ and goarch_ can be specified as attributes. 67 Both of these can take one of the values "on", "off" or "auto", and "auto" is the default. 68 69 +--------------+-------------------------------------------------------------------------+ 70 | on | Forces the feature to be turned on for this binary. | 71 +--------------+-------------------------------------------------------------------------+ 72 | off | This forces the feature to be turned off for the binary even if it is | 73 | | enabled on the command line. | 74 +--------------+-------------------------------------------------------------------------+ 75 | auto | The default, it means obey whatever the command line suggests. | 76 +--------------+-------------------------------------------------------------------------+ 77 78 The mode structure 79 ~~~~~~~~~~~~~~~~~~ 80 81 The build mode structure is handed to all low level go build action. It has the 82 following fields that control the bevhaviour of those actions: 83 84 * static_ 85 * race_ 86 * msan_ 87 * pure_ 88 * link_ 89 * debug_ 90 * strip_ 91 * goos_ 92 * goarch_ 93 94 Build modes 95 ----------- 96 97 The following is a description of the build modes. Not all build modes are truly independent, but 98 most combinations are valid. 99 100 static 101 ~~~~~~ 102 103 Causes any cgo code to be statically linked in to the go binary. 104 105 race 106 ~~~~ 107 108 Causes the binary to be built with race detection enabled. Most often used when 109 running tests. 110 111 msan 112 ~~~~ 113 114 Causes go code to be built with support for the clang memory sanitizer. 115 116 pure 117 ~~~~ 118 119 Compiles go code with :code:`CGO_ENABLED=0`. Mostly often used to force go code to not 120 link against libc. 121 122 link 123 ~~~~ 124 125 | This is not yet working, and there is no mechaism to actually control the link mode, 126 | so it is always the default value of "normal" 127 128 Controls the linking mode, must be one of 129 130 +--------------+------------------------------------------------------------------+ 131 | normal | This is the default, builds executables. | 132 +--------------+------------------------------------------------------------------+ 133 | shared | Links to a shared go library. | 134 +--------------+------------------------------------------------------------------+ 135 | c-shared | Links to a shared c library. | 136 +--------------+------------------------------------------------------------------+ 137 | pie | Links a position independent executables | 138 +--------------+------------------------------------------------------------------+ 139 | plugin | Links to a go plugin. | 140 +--------------+------------------------------------------------------------------+ 141 142 debug 143 ~~~~~ 144 145 This compiles with full support for debugging, specifically it compiles with 146 optimizations disabled and inlining off. 147 148 strip 149 ~~~~~ 150 151 Causes debugging information to be stripped from the binaries. 152 153 goos 154 ~~~~ 155 156 This controls which operating system to target. 157 158 goarch 159 ~~~~~~ 160 161 This controls which architecture to target. 162 163 Using build modes 164 ----------------- 165 166 167 Building pure go binaries 168 ~~~~~~~~~~~~~~~~~~~~~~~~~ 169 170 You can switch the default binaries to non cgo using 171 172 .. code:: bash 173 174 bazel build --features=pure //:my_binary 175 176 You can build pure go binaries by setting those attributes on a binary. 177 178 .. code:: bzl 179 180 go_binary( 181 name = "foo", 182 srcs = ["foo.go"], 183 pure = "on", 184 ) 185 186 187 Building static binaries 188 ~~~~~~~~~~~~~~~~~~~~~~~~ 189 190 | Note that static linking does not work on darwin. 191 192 You can switch the default binaries to statically linked binaries using 193 194 .. code:: bash 195 196 bazel build --features=static //:my_binary 197 198 You can build static go binaries by setting those attributes on a binary. 199 If you want it to be fully static (no libc), you should also specify pure. 200 201 .. code:: bzl 202 203 go_binary( 204 name = "foo", 205 srcs = ["foo.go"], 206 static = "on", 207 ) 208 209 210 Using the race detector 211 ~~~~~~~~~~~~~~~~~~~~~~~ 212 213 You can switch the default binaries to race detection mode, and thus also switch 214 the mode of tests by using 215 216 .. code:: 217 218 bazel test --features=race //... 219 220 but in general it is strongly recommended instead to turn it on for specific tests. 221 222 .. code:: 223 224 go_test( 225 name = "go_default_test", 226 srcs = ["lib_test.go"], 227 embed = [":go_default_library"], 228 race = "on", 229 ) 230