tools/gn/docs/quick_start.md

   1 # GN Quick Start guide
   2
   3 [TOC]
   4
   5 ## Running GN
   6
   7 You just run `gn` from the command line. There is a script in
   8 depot\_tools (which is presumably on your path) with this name. The
   9 script will find the binary in the source tree containing the current
  10 directory and run it.
  11
  12 ## Setting up a build
  13
  14 In GYP, the system would generate `Debug` and `Release` build
  15 directories for you and configure them accordingly. GN doesn't do this.
  16 Instead, you set up whatever build directory you want with whatever
  17 configuration you want. The Ninja files will be automatically
  18 regenerated if they're out of date when you build in that directory.
  19
  20 To make a build directory:
  21
  22 ```
  23 gn gen out/my_build
  24 ```
  25
  26 ## Passing build arguments
  27
  28 Set build arguments on your build directory by running:
  29
  30 ```
  31 gn args out/my_build
  32 ```
  33
  34 This will bring up an editor. Type build args into that file like this:
  35
  36 ```
  37 is_component_build = true
  38 is_debug = false
  39 ```
  40
  41 You can see the list of available arguments and their default values by
  42 typing
  43
  44 ```
  45 gn args --list out/my_build
  46 ```
  47
  48 on the command line. See "Taking build arguments" below for information
  49 on how to use these in your code. (Note that you have to specify the
  50 build directory for this command because the available arguments can
  51 change according to what's set.
  52
  53 ## Cross-compiling to a target OS or architecture
  54
  55 Run `gn args out/Default` (substituting your build directory as needed) and
  56 add one or more of the following lines for common cross-compiling options.
  57
  58 ```
  59 target_os = "chromeos"
  60 target_os = "android"
  61
  62 target_cpu = "arm"
  63 target_cpu = "x86"
  64 target_cpu = "x64"
  65 ```
  66
  67 See [GNCrossCompiles](cross_compiles.md) for more info.
  68
  69 ## Configuring goma
  70
  71
  72 Run `gn args out/Default` (substituting your build directory as needed).
  73 Add:
  74
  75 ```
  76 use_goma = true
  77 goma_dir = "~/foo/bar/goma"
  78 ```
  79
  80 If your goma is in the default location (`~/goma`) then you can omit the
  81 `goma_dir` line.
  82
  83 ## Configuring component mode
  84
  85 This is a build arg like the goma flags. run `gn args out/Default` and add:
  86
  87 ```
  88 is_component_build = true
  89 ```
  90
  91 ## Step-by-step
  92
  93 ### Adding a build file
  94
  95 Create a `tools/gn/tutorial/BUILD.gn` file and enter the following:
  96
  97 ```
  98 executable("hello_world") {
  99   sources = [
 100     "hello_world.cc",
 101   ]
 102 }
 103 ```
 104
 105 There should already be a `hello_world.cc` file in that directory,
 106 containing what you expect. That's it! Now we just need to tell the
 107 build about this file. Open the `BUILD.gn` file in the root directory
 108 and add the label of this target to the dependencies of one of the root
 109 groups (a "group" target is a meta-target that is just a collection of
 110 other targets):
 111
 112 ```
 113 group("root") {
 114   deps = [
 115     ...
 116     "//url",
 117     "//tools/gn/tutorial:hello_world",
 118   ]
 119 }
 120 ```
 121
 122 You can see the label of your target is "//" (indicating the source
 123 root), followed by the directory name, a colon, and the target name.
 124
 125 ### Testing your addition
 126
 127 From the command line in the source root directory:
 128
 129 ```
 130 gn gen out/Default
 131 ninja -C out/Default hello_world
 132 out/Default/hello_world
 133 ```
 134
 135 GN encourages target names for static libraries that aren't globally
 136 unique. To build one of these, you can pass the label with no leading
 137 "//" to ninja:
 138
 139 ```
 140 ninja -C out/Default tools/gn/tutorial:hello_world
 141 ```
 142
 143 ### Declaring dependencies
 144
 145 Let's make a static library that has a function to say hello to random
 146 people. There is a source file `hello.cc` in that directory which has a
 147 function to do this. Open the `tools/gn/tutorial/BUILD.gn` file and add
 148 the static library to the bottom of the existing file:
 149
 150 ```
 151 static_library("hello") {
 152   sources = [
 153     "hello.cc",
 154   ]
 155 }
 156 ```
 157
 158 Now let's add an executable that depends on this library:
 159
 160 ```
 161 executable("say_hello") {
 162   sources = [
 163     "say_hello.cc",
 164   ]
 165   deps = [
 166     ":hello",
 167   ]
 168 }
 169 ```
 170
 171 This executable includes one source file and depends on the previous
 172 static library. The static library is referenced by its label in the
 173 `deps`. You could have used the full label `//tools/gn/tutorial:hello`
 174 but if you're referencing a target in the same build file, you can use
 175 the shortcut `:hello`.
 176
 177 ### Test the static library version
 178
 179 From the command line in the source root directory:
 180
 181 ```
 182 ninja -C out/Default say_hello
 183 out/Default/say_hello
 184 ```
 185
 186 Note that you **didn't** need to re-run GN. GN will automatically rebuild
 187 the ninja files when any build file has changed. You know this happens
 188 when ninja prints `[1/1] Regenerating ninja files` at the beginning of
 189 execution.
 190
 191 ### Compiler settings
 192
 193 Our hello library has a new feature, the ability to say hello to two
 194 people at once. This feature is controlled by defining `TWO_PEOPLE`. We
 195 can add defines like so:
 196
 197 ```
 198 static_library("hello") {
 199   sources = [
 200     "hello.cc",
 201   ]
 202   defines = [
 203     "TWO_PEOPLE",
 204   ]
 205 }
 206 ```
 207
 208 ### Putting settings in a config
 209
 210 However, users of the library also need to know about this define, and
 211 putting it in the static library target defines it only for the files
 212 there. If somebody else includes `hello.h`, they won't see the new
 213 definition. To see the new definition, everybody will have to define
 214 `TWO_PEOPLE`.
 215
 216 GN has a concept called a "config" which encapsulates settings. Let's
 217 create one that defines our preprocessor define:
 218
 219 ```
 220 config("hello_config") {
 221   defines = [
 222     "TWO_PEOPLE",
 223   ]
 224 }
 225 ```
 226
 227 To apply these settings to your target, you only need to add the
 228 config's label to the list of configs in the target:
 229
 230 ```
 231 static_library("hello") {
 232   ...
 233   configs += [
 234     ":hello_config",
 235   ]
 236 }
 237 ```
 238
 239 Note that you need "+=" here instead of "=" since the build
 240 configuration has a default set of configs applied to each target that
 241 set up the default build stuff. You want to add to this list rather than
 242 overwrite it. To see the default configs, you can use the `print`
 243 function in the build file or the `desc` command-line subcommand (see
 244 below for examples of both).
 245
 246 ### Dependent configs
 247
 248 This nicely encapsulates our settings, but still requires everybody that
 249 uses our library to set the config on themselves. It would be nice if
 250 everybody that depends on our `hello` library can get this
 251 automatically. Change your library definition to:
 252
 253 ```
 254 static_library("hello") {
 255   sources = [
 256     "hello.cc",
 257   ]
 258   all_dependent_configs = [
 259     ":hello_config"
 260   ]
 261 }
 262 ```
 263
 264 This applies the `hello_config` to the `hello` target itself, plus all
 265 targets that depend on transitively depend on the current one. Now
 266 everybody that depends on us will get our settings. You can also set
 267 `public_configs` which applies only to targets that directly
 268 depend on your target (not transitively).
 269
 270 Now if you compile and run, you'll see the new version with two people:
 271
 272 ```
 273 > ninja -C out/Default say_hello
 274 ninja: Entering directory 'out/Default'
 275 [1/1] Regenerating ninja files
 276 [4/4] LINK say_hello
 277 > out/Default/say_hello
 278 Hello, Bill and Joy.
 279 ```
 280
 281 ## Don't know what's going on?
 282
 283 You can run GN in verbose mode to see lots of messages about what it's
 284 doing. Use `-v` for this.
 285
 286 ### Print debugging
 287
 288 There is a `print` command which just writes to stdout:
 289
 290 ```
 291 static_library("hello") {
 292   ...
 293   print(configs)
 294 }
 295 ```
 296
 297 This will print all of the configs applying to your target (including
 298 the default ones).
 299
 300 ### The "desc" command
 301
 302 You can run `gn desc <build_dir> <targetname>` to get information about
 303 a given target:
 304
 305 ```
 306 gn desc out/Default //tools/gn/tutorial:say_hello
 307 ```
 308
 309 will print out lots of exciting information. You can also print just one
 310 section. Lets say you wanted to know where your `TWO_PEOPLE` define
 311 came from on the `say_hello` target:
 312
 313 ```
 314 > gn desc out/Default //tools/gn/tutorial:say_hello defines --blame
 315 ...lots of other stuff omitted...
 316   From //tools/gn/tutorial:hello_config
 317        (Added by //tools/gn/tutorial/BUILD.gn:12)
 318     TWO_PEOPLE
 319 ```
 320
 321 You can see that `TWO_PEOPLE` was defined by a config, and you can also
 322 see the which like caused that config to be applied to your target (in
 323 this case, the `all_dependent_configs` line).
 324
 325 Another particularly interesting variation:
 326
 327 ```
 328 gn desc out/Default //base:base_i18n deps --tree
 329 ```
 330
 331 See `gn help desc` for more.
 332
 333 ### Performance
 334
 335 You can see what took a long time by running it with the --time command
 336 line flag. This will output a summary of timings for various things.
 337
 338 You can also make a trace of how the build files were executed:
 339
 340 ```
 341 gn --tracelog=mylog.trace
 342 ```
 343
 344 and you can load the resulting file in Chrome's `about:tracing` page to
 345 look at everything.