OLD | NEW |
1 # GN Language and Operation | 1 # GN Language and Operation |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 | 4 |
5 ## Introduction | 5 ## Introduction |
6 | 6 |
7 This page describes many of the language details and behaviors. | 7 This page describes many of the language details and behaviors. |
8 | 8 |
9 ### Use the built-in help! | 9 ### Use the built-in help! |
10 | 10 |
(...skipping 245 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
256 "//base/test/foo.cc" | 256 "//base/test/foo.cc" |
257 ``` | 257 ``` |
258 | 258 |
259 System absolute names (rare, normally used for include directories): | 259 System absolute names (rare, normally used for include directories): |
260 | 260 |
261 ``` | 261 ``` |
262 "/usr/local/include/" | 262 "/usr/local/include/" |
263 "/C:/Program Files/Windows Kits/Include" | 263 "/C:/Program Files/Windows Kits/Include" |
264 ``` | 264 ``` |
265 | 265 |
266 ### Labels | |
267 | |
268 Everything that can participate in the dependency graph (targets, | |
269 configs, and toolchains) are identified by labels which are strings of a | |
270 defined format. A common label looks like this: | |
271 | |
272 ``` | |
273 "//base/test:test_support" | |
274 ``` | |
275 | |
276 which consists of a source-root-absolute path, a colon, and a name. This | |
277 means to look for the thing named "test\_support" in | |
278 `src/base/test/BUILD.gn`. | |
279 | |
280 When loading a build file, if it doesn't exist in the given location | |
281 relative to the source root, GN will look in the secondary tree in | |
282 `build/secondary`. The structure of this tree mirrors the main | |
283 repository and is a way to add build files for directories that may be | |
284 pulled from other repositories where we can't easily check in BUILD | |
285 files. The secondary tree is a fallback rather than an override, so a file in | |
286 the normal location always takes precedence. | |
287 | |
288 A canonical label also includes the label of the toolchain being used. | |
289 Normally, the toolchain label is implicitly inherited, but you can | |
290 include it to specify cross-toolchain dependencies (see "Toolchains" | |
291 below). | |
292 | |
293 ``` | |
294 "//base/test:test_support(//build/toolchain/win:msvc)" | |
295 ``` | |
296 | |
297 In this case it will look for the toolchain definition called "msvc" | |
298 in the file `//build/toolchain/win` to know how to compile this target. | |
299 | |
300 If you want to refer to something in the same buildfile, you can omit | |
301 the path name and just start with a colon. | |
302 | |
303 ``` | |
304 ":base" | |
305 ``` | |
306 | |
307 Labels can be specified as being relative to the current directory. | |
308 Stylistically, we prefer to use absolute paths for all non-file-local | |
309 references unless a build file needs to be run in different contexts (like | |
310 a project needs to be both standalone and pulled into other projects in | |
311 difference places in the directory hierarchy). | |
312 | |
313 ``` | |
314 "source/plugin:myplugin" # Prefer not to do these. | |
315 "../net:url_request" | |
316 ``` | |
317 | |
318 If a name is unspecified, it will inherit the directory name. Stylistically, we | |
319 prefer to omit the colon and name in these cases. | |
320 | |
321 ``` | |
322 "//net" = "//net:net" | |
323 "//tools/gn" = "//tools/gn:gn" | |
324 ``` | |
325 | |
326 ## Build configuration | 266 ## Build configuration |
327 | 267 |
328 ### Overall build flow | |
329 | |
330 1. Look for `.gn` file in the current directory and walk up the | |
331 directory tree until one is found. Set this directory to be the | |
332 "source root" and interpret this file to find the name of the build | |
333 config file. | |
334 2. Execute the build config file (this is the default toolchain). In Chrome | |
335 this is `//build/config/BUILDCONFIG.gn`. | |
336 3. Load the `BUILD.gn` file in the root directory. | |
337 4. Recursively load `BUILD.gn` in other directories to resolve all | |
338 current dependencies. If a BUILD file isn't found in the specified | |
339 location, GN will look in the corresponding location inside | |
340 `build/secondary`. | |
341 5. When a target's dependencies are resolved, write out the `.ninja` | |
342 file to disk. | |
343 6. When all targets are resolved, write out the root `build.ninja` | |
344 file. If the top-level build file defines a group called "default" | |
345 (i.e., `//:default`), GN will tell Ninja to use that for the | |
346 default build target, rather than building everything. (You can | |
347 still use `ninja all` to build everything). | |
348 | |
349 ### The build config file | |
350 | |
351 The first file executed is the build config file. The name of this file | |
352 is specified in the `.gn` file that marks the root of the repository. In | |
353 Chrome it is `//build/config/BUILDCONFIG.gn`. There is only one build | |
354 config file. | |
355 | |
356 This file sets up the scope in which all other build files will execute. | |
357 Any arguments, variables, defaults, etc. set up in this file will be | |
358 visible to all files in the build. | |
359 | |
360 It is executed once for each toolchain (see "Toolchains"). | |
361 | |
362 ### Build arguments | |
363 | |
364 Arguments can be passed in from the command line (and from other | |
365 toolchains, see "Toolchains" below). You declare which arguments you | |
366 accept and specify default values via `declare_args`. | |
367 | |
368 See `gn help buildargs` for an overview of how this works. See `gn help | |
369 declare_args` for specifics on declaring them. | |
370 | |
371 It is an error to declare a given argument more than once in a given | |
372 scope. Typically arguments would be declared in an imported file (to | |
373 share them among some subset of the build) or in the main build config | |
374 file (to make them global). | |
375 | |
376 ### Target defaults | |
377 | |
378 You can set up some default values for a given target type. This is | |
379 normally done in the build config file to set a list of default configs | |
380 that defines the build flags and other setup information for each target | |
381 type. | |
382 | |
383 See `gn help set_defaults`. | |
384 | |
385 For example, when you declare a `static_library`, the target defaults | |
386 for a static library are applied. These values can be overwritten, | |
387 modified, or preserved by a target. | |
388 | |
389 ``` | |
390 # This call is typically in the build config file (see above). | |
391 set_defaults("static_library") { | |
392 configs = [ "//build:rtti_setup", "//build:extra_warnings" ] | |
393 } | |
394 | |
395 # This would be in your directory's BUILD.gn file. | |
396 static_library("mylib") { | |
397 # At this point configs is set to [ "//build:rtti_setup", "//build:extra_warni
ngs" ] | |
398 # by default but may be modified. | |
399 configs -= "//build:extra_warnings" # Don't want these warnings. | |
400 configs += ":mylib_config" # Add some more configs. | |
401 } | |
402 ``` | |
403 | |
404 The other use-case for setting target defaults is when you define your | |
405 own target type via `template` and want to specify certain default | |
406 values. | |
407 | |
408 ## Targets | 268 ## Targets |
409 | 269 |
410 A target is a node in the build graph. It usually represents some kind | 270 A target is a node in the build graph. It usually represents some kind |
411 of executable or library file that will be generated. Targets depend on | 271 of executable or library file that will be generated. Targets depend on |
412 other targets. The built-in target types (see `gn help <targettype>` for | 272 other targets. The built-in target types (see `gn help <targettype>` for |
413 more help) are: | 273 more help) are: |
414 | 274 |
415 * `action`: Run a script to generate a file. | 275 * `action`: Run a script to generate a file. |
416 * `action_foreach`: Run a script once for each source file. | 276 * `action_foreach`: Run a script once for each source file. |
417 * `bundle_data`: Declare data to go into a Mac/iOS bundle. | 277 * `bundle_data`: Declare data to go into a Mac/iOS bundle. |
(...skipping 90 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
508 ``` | 368 ``` |
509 | 369 |
510 A target can forward a config to all dependents until a link boundary is | 370 A target can forward a config to all dependents until a link boundary is |
511 reached by setting it as an `all_dependent_config`. This is strongly | 371 reached by setting it as an `all_dependent_config`. This is strongly |
512 discouraged as it can spray flags and defines over more of the build than | 372 discouraged as it can spray flags and defines over more of the build than |
513 necessary. Instead, use public_deps to control which flags apply where. | 373 necessary. Instead, use public_deps to control which flags apply where. |
514 | 374 |
515 In Chrome, prefer the build flag header system (`build/buildflag_header.gni`) | 375 In Chrome, prefer the build flag header system (`build/buildflag_header.gni`) |
516 for defines which prevents most screw-ups with compiler defines. | 376 for defines which prevents most screw-ups with compiler defines. |
517 | 377 |
518 ## Toolchains | |
519 | |
520 A toolchain is a set of build commands to run for different types of | |
521 input files and link tasks. | |
522 | |
523 You can have multiple toolchains in the build. It's easiest to think | |
524 about each one as completely separate builds that can additionally have | |
525 dependencies between them. This means, for example, that the 32-bit | |
526 Windows build might depend on a 64-bit helper target. Each of them can | |
527 depend on `"//base:base"` which will be the 32-bit base in the context | |
528 of the 32-bit toolchain, and the 64-bit base in the context of the | |
529 64-bit toolchain | |
530 | |
531 When a target specifies a dependency on another target, the current | |
532 toolchain is inherited unless it is explicitly overridden (see "Labels" | |
533 above). | |
534 | |
535 ### Toolchains and the build configuration | |
536 | |
537 When you have a simple build with only one toolchain, the build config | |
538 file is loaded only once at the beginning of the build. It must call | |
539 `set_default_toolchain` to tell GN the label of the toolchain definition | |
540 to use. This toolchain definition has the commands to use for the | |
541 compiler and linker. The `toolchain_args` section of the toolchain | |
542 definition is ignored. | |
543 | |
544 When a target has a dependency on a target using different toolchain, GN | |
545 will start a build using that secondary toolchain to resolve the target. | |
546 GN will load the build config file with the arguments specified in the | |
547 toolchain definition. Since the toolchain is already known, calls to | |
548 `set_default_toolchain` are ignored. | |
549 | |
550 So the toolchain configuration is two-way. In the default toolchain | |
551 (i.e. the main build target) the configuration flows from the build | |
552 config file to the toolchain: the build config file looks at the state | |
553 of the build (OS type, CPU architecture, etc.) and decides which | |
554 toolchain to use (via `set_default_toolchain`). In secondary toolchains, | |
555 the configuration flows from the toolchain to the build config file: the | |
556 `toolchain_args` in the toolchain definition specifies the arguments to | |
557 re-invoke the build. | |
558 | |
559 ### Toolchain example | |
560 | |
561 Say the default build is a 64-bit build. Either this is the default CPU | |
562 architecture based on the current system, or the user has passed | |
563 `target_cpu="x64"` on the command line. The build config file might look | |
564 like this to set up the default toolchain: | |
565 | |
566 ``` | |
567 # Set default toolchain only has an effect when run in the context of | |
568 # the default toolchain. Pick the right one according to the current CPU | |
569 # architecture. | |
570 if (target_cpu == "x64") { | |
571 set_default_toolchain("//toolchains:64") | |
572 } else if (target_cpu == "x86") { | |
573 set_default_toolchain("//toolchains:32") | |
574 } | |
575 ``` | |
576 | |
577 If a 64-bit target wants to depend on a 32-bit binary, it would specify | |
578 a dependency using `data_deps` (data deps are like deps that are only | |
579 needed at runtime and aren't linked, since you can't link a 32-bit and a | |
580 64-bit library). | |
581 | |
582 ``` | |
583 executable("my_program") { | |
584 ... | |
585 if (target_cpu == "x64") { | |
586 # The 64-bit build needs this 32-bit helper. | |
587 data_deps = [ ":helper(//toolchains:32)" ] | |
588 } | |
589 } | |
590 | |
591 if (target_cpu == "x86") { | |
592 # Our helper library is only compiled in 32-bits. | |
593 shared_library("helper") { | |
594 ... | |
595 } | |
596 } | |
597 ``` | |
598 | |
599 The toolchain file referenced above (`toolchains/BUILD.gn`) would define | |
600 two toolchains: | |
601 | |
602 ``` | |
603 toolchain("32") { | |
604 tool("cc") { | |
605 ... | |
606 } | |
607 ... more tools ... | |
608 | |
609 # Arguments to the build when re-invoking as a secondary toolchain. | |
610 toolchain_args = { | |
611 current_cpu = "x86" | |
612 } | |
613 } | |
614 | |
615 toolchain("64") { | |
616 tool("cc") { | |
617 ... | |
618 } | |
619 ... more tools ... | |
620 | |
621 # Arguments to the build when re-invoking as a secondary toolchain. | |
622 toolchain_args = { | |
623 current_cpu = "x64" | |
624 } | |
625 } | |
626 ``` | |
627 | |
628 The toolchain args specifies the CPU architecture explicitly, so if a | |
629 target depends on something using that toolchain, that cpu architecture | |
630 will be set when re-invoking the build. These args are ignored for the | |
631 default toolchain since by the time they're known the build config has | |
632 already been run. In general, the toolchain args and the conditions used | |
633 to set the default toolchain should agree. | |
634 | |
635 The nice thing about the multiple-build setup is that you can write | |
636 conditionals in your targets referencing the current toolchain state. | |
637 The build files will be re-run with different state for each toolchain. | |
638 For the `my_program` example above, you can see it queries the CPU | |
639 architecture, adding a dependency only for the 64-bit build of the | |
640 program. The 32-bit build would not get this dependency. | |
641 | |
642 ### Declaring a toolchain | |
643 | |
644 Toolchains are declared with the `toolchain` command, which sets the | |
645 commands to use for each compile and link operation. The toolchain also | |
646 specifies a set of arguments to pass to the build config file when | |
647 executing. This allows you to pass configuration information to the | |
648 alternate toolchain. | |
649 | |
650 ## Templates | 378 ## Templates |
651 | 379 |
652 Templates are GN's primary way to re-use code. Typically, a template | 380 Templates are GN's primary way to re-use code. Typically, a template |
653 would expand to one or more other target types. | 381 would expand to one or more other target types. |
654 | 382 |
655 ``` | 383 ``` |
656 # Declares a script that compiles IDL files to source, and then compiles those | 384 # Declares a script that compiles IDL files to source, and then compiles those |
657 # source files. | 385 # source files. |
658 template("idl") { | 386 template("idl") { |
659 # Always base helper targets on target_name so they're unique. Target name | 387 # Always base helper targets on target_name so they're unique. Target name |
(...skipping 144 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
804 GN keeps some GYP concept like "all dependent" settings which work a bit | 532 GN keeps some GYP concept like "all dependent" settings which work a bit |
805 differently in Blaze. This is partially to make conversion from the existing | 533 differently in Blaze. This is partially to make conversion from the existing |
806 GYP code easier, and the GYP constructs generally offer more fine-grained | 534 GYP code easier, and the GYP constructs generally offer more fine-grained |
807 control (which is either good or bad, depending on the situation). | 535 control (which is either good or bad, depending on the situation). |
808 | 536 |
809 GN also uses GYP names like "sources" instead of "srcs" since | 537 GN also uses GYP names like "sources" instead of "srcs" since |
810 abbreviating this seems needlessly obscure, although it uses Blaze's | 538 abbreviating this seems needlessly obscure, although it uses Blaze's |
811 "deps" since "dependencies" is so hard to type. Chromium also compiles | 539 "deps" since "dependencies" is so hard to type. Chromium also compiles |
812 multiple languages in one target so specifying the language type on the | 540 multiple languages in one target so specifying the language type on the |
813 target name prefix was dropped (e.g. from `cc_library`). | 541 target name prefix was dropped (e.g. from `cc_library`). |
OLD | NEW |