| OLD | NEW |
|---|
| (Empty) |
| 1 # GYP (Generate Your Projects) User Documentation | |
| 2 | |
| 3 Status: Draft (as of 2009-05-19) | |
| 4 | |
| 5 Mark Mentovai <mark@chromium.org>, | |
| 6 Steven Knight <sgk@chromium.org> | |
| 7 _et al._ | |
| 8 | |
| 9 Modified: 2009-05-19 | |
| 10 | |
| 11 [TOC] | |
| 12 | |
| 13 ## Introduction | |
| 14 | |
| 15 This document is intended to provide a user-level guide to GYP. The | |
| 16 emphasis here is on how to use GYP to accomplish specific tasks, not on | |
| 17 the complete technical language specification. (For that, see the | |
| 18 [LanguageSpecification](LanguageSpecification).) | |
| 19 | |
| 20 The document below starts with some overviews to provide context: an | |
| 21 overview of the structure of a `.gyp` file itself, an overview of a | |
| 22 typical executable-program target in a `.gyp` file, an an overview of a | |
| 23 typical library target in a `.gyp` file. | |
| 24 | |
| 25 After the overviews, there are examples of `gyp` patterns for different | |
| 26 common use cases. | |
| 27 | |
| 28 ## Skeleton of a typical Chromium .gyp file | |
| 29 | |
| 30 Here is the skeleton of a typical `.gyp` file in the Chromium tree: | |
| 31 | |
| 32 ``` | |
| 33 { | |
| 34 'variables': { | |
| 35 . | |
| 36 . | |
| 37 . | |
| 38 }, | |
| 39 'includes': [ | |
| 40 '../build/common.gypi', | |
| 41 ], | |
| 42 'target_defaults': { | |
| 43 . | |
| 44 . | |
| 45 . | |
| 46 }, | |
| 47 'targets': [ | |
| 48 { | |
| 49 'target_name': 'target_1', | |
| 50 . | |
| 51 . | |
| 52 . | |
| 53 }, | |
| 54 { | |
| 55 'target_name': 'target_2', | |
| 56 . | |
| 57 . | |
| 58 . | |
| 59 }, | |
| 60 ], | |
| 61 'conditions': [ | |
| 62 ['OS=="linux"', { | |
| 63 'targets': [ | |
| 64 { | |
| 65 'target_name': 'linux_target_3', | |
| 66 . | |
| 67 . | |
| 68 . | |
| 69 }, | |
| 70 ], | |
| 71 }], | |
| 72 ['OS=="win"', { | |
| 73 'targets': [ | |
| 74 { | |
| 75 'target_name': 'windows_target_4', | |
| 76 . | |
| 77 . | |
| 78 . | |
| 79 }, | |
| 80 ], | |
| 81 }, { # OS != "win" | |
| 82 'targets': [ | |
| 83 { | |
| 84 'target_name': 'non_windows_target_5', | |
| 85 . | |
| 86 . | |
| 87 . | |
| 88 }, | |
| 89 }], | |
| 90 ], | |
| 91 } | |
| 92 ``` | |
| 93 | |
| 94 The entire file just contains a Python dictionary. (It's actually JSON, | |
| 95 with two small Pythonic deviations: comments are introduced with `#`, | |
| 96 and a `,` (comma)) is legal after the last element in a list or | |
| 97 dictionary.) | |
| 98 | |
| 99 The top-level pieces in the `.gyp` file are as follows: | |
| 100 | |
| 101 `'variables'`: Definitions of variables that can be interpolated and | |
| 102 used in various other parts of the file. | |
| 103 | |
| 104 `'includes'`: A list of of other files that will be included in this | |
| 105 file. By convention, included files have the suffix `.gypi` (gyp | |
| 106 include). | |
| 107 | |
| 108 `'target_defaults'`: Settings that will apply to _all_ of the targets | |
| 109 defined in this `.gyp` file. | |
| 110 | |
| 111 `'targets'`: The list of targets for which this `.gyp` file can | |
| 112 generate builds. Each target is a dictionary that contains settings | |
| 113 describing all the information necessary to build the target. | |
| 114 | |
| 115 `'conditions'`: A list of condition specifications that can modify the | |
| 116 contents of the items in the global dictionary defined by this `.gyp` | |
| 117 file based on the values of different variablwes. As implied by the | |
| 118 above example, the most common use of a `conditions` section in the | |
| 119 top-level dictionary is to add platform-specific targets to the | |
| 120 `targets` list. | |
| 121 | |
| 122 ## Skeleton of a typical executable target in a .gyp file | |
| 123 | |
| 124 The most straightforward target is probably a simple executable program. | |
| 125 Here is an example `executable` target that demonstrates the features | |
| 126 that should cover most simple uses of gyp: | |
| 127 | |
| 128 ``` | |
| 129 { | |
| 130 'targets': [ | |
| 131 { | |
| 132 'target_name': 'foo', | |
| 133 'type': 'executable', | |
| 134 'msvs_guid': '5ECEC9E5-8F23-47B6-93E0-C3B328B3BE65', | |
| 135 'dependencies': [ | |
| 136 'xyzzy', | |
| 137 '../bar/bar.gyp:bar', | |
| 138 ], | |
| 139 'defines': [ | |
| 140 'DEFINE_FOO', | |
| 141 'DEFINE_A_VALUE=value', | |
| 142 ], | |
| 143 'include_dirs': [ | |
| 144 '..', | |
| 145 ], | |
| 146 'sources': [ | |
| 147 'file1.cc', | |
| 148 'file2.cc', | |
| 149 ], | |
| 150 'conditions': [ | |
| 151 ['OS=="linux"', { | |
| 152 'defines': [ | |
| 153 'LINUX_DEFINE', | |
| 154 ], | |
| 155 'include_dirs': [ | |
| 156 'include/linux', | |
| 157 ], | |
| 158 }], | |
| 159 ['OS=="win"', { | |
| 160 'defines': [ | |
| 161 'WINDOWS_SPECIFIC_DEFINE', | |
| 162 ], | |
| 163 }, { # OS != "win", | |
| 164 'defines': [ | |
| 165 'NON_WINDOWS_DEFINE', | |
| 166 ], | |
| 167 }] | |
| 168 ], | |
| 169 }, | |
| 170 ], | |
| 171 } | |
| 172 ``` | |
| 173 | |
| 174 The top-level settings in the target include: | |
| 175 | |
| 176 `'target_name'`: The name by which the target should be known, which | |
| 177 should be unique across all `.gyp` files. This name will be used as the | |
| 178 project name in the generated Visual Studio solution, as the target name | |
| 179 in the generated XCode configuration, and as the alias for building this | |
| 180 target from the command line of the generated SCons configuration. | |
| 181 | |
| 182 `'type'`: Set to `executable`, logically enough. | |
| 183 | |
| 184 `'msvs_guid'`: THIS IS ONLY TRANSITIONAL. This is a hard-coded GUID | |
| 185 values that will be used in the generated Visual Studio solution | |
| 186 file(s). This allows us to check in a `chrome.sln` file that | |
| 187 interoperates with gyp-generated project files. Once everything in | |
| 188 Chromium is being generated by gyp, it will no longer be important that | |
| 189 the GUIDs stay constant across invocations, and we'll likely get rid of | |
| 190 these settings, | |
| 191 | |
| 192 `'dependencies'`: This lists other targets that this target depends on. | |
| 193 The gyp-generated files will guarantee that the other targets are built | |
| 194 before this target. Any library targets in the `dependencies` list will | |
| 195 be linked with this target. The various settings (`defines`, | |
| 196 `include_dirs`, etc.) listed in the `direct_dependent_settings` sections | |
| 197 of the targets in this list will be applied to how _this_ target is | |
| 198 built and linked. See the more complete discussion of | |
| 199 `direct_dependent_settings`, below. | |
| 200 | |
| 201 `'defines'`: The C preprocessor definitions that will be passed in on | |
| 202 compilation command lines (using `-D` or `/D` options). | |
| 203 | |
| 204 `'include_dirs'`: The directories in which included header files live. | |
| 205 These will be passed in on compilation command lines (using `-I` or `/I` | |
| 206 options). | |
| 207 | |
| 208 `'sources'`: The source files for this target. | |
| 209 | |
| 210 `'conditions'`: A block of conditions that will be evaluated to update | |
| 211 the different settings in the target dictionary. | |
| 212 | |
| 213 ## Skeleton of a typical library target in a .gyp file | |
| 214 | |
| 215 The vast majority of targets are libraries. Here is an example of a | |
| 216 library target including the additional features that should cover most | |
| 217 needs of libraries: | |
| 218 | |
| 219 ``` | |
| 220 { | |
| 221 'targets': [ | |
| 222 { | |
| 223 'target_name': 'foo', | |
| 224 'type': '<(library)' | |
| 225 'msvs_guid': '5ECEC9E5-8F23-47B6-93E0-C3B328B3BE65', | |
| 226 'dependencies': [ | |
| 227 'xyzzy', | |
| 228 '../bar/bar.gyp:bar', | |
| 229 ], | |
| 230 'defines': [ | |
| 231 'DEFINE_FOO', | |
| 232 'DEFINE_A_VALUE=value', | |
| 233 ], | |
| 234 'include_dirs': [ | |
| 235 '..', | |
| 236 ], | |
| 237 'direct_dependent_settings': { | |
| 238 'defines': [ | |
| 239 'DEFINE_FOO', | |
| 240 'DEFINE_ADDITIONAL', | |
| 241 ], | |
| 242 'linkflags': [ | |
| 243 ], | |
| 244 }, | |
| 245 'export_dependent_settings': [ | |
| 246 '../bar/bar.gyp:bar', | |
| 247 ], | |
| 248 'sources': [ | |
| 249 'file1.cc', | |
| 250 'file2.cc', | |
| 251 ], | |
| 252 'conditions': [ | |
| 253 ['OS=="linux"', { | |
| 254 'defines': [ | |
| 255 'LINUX_DEFINE', | |
| 256 ], | |
| 257 'include_dirs': [ | |
| 258 'include/linux', | |
| 259 ], | |
| 260 ], | |
| 261 ['OS=="win"', { | |
| 262 'defines': [ | |
| 263 'WINDOWS_SPECIFIC_DEFINE', | |
| 264 ], | |
| 265 }, { # OS != "win", | |
| 266 'defines': [ | |
| 267 'NON_WINDOWS_DEFINE', | |
| 268 ], | |
| 269 }] | |
| 270 ], | |
| 271 ], | |
| 272 } | |
| 273 ``` | |
| 274 | |
| 275 The possible entries in a library target are largely the same as those | |
| 276 that can be specified for an executable target (`defines`, | |
| 277 `include_dirs`, etc.). The differences include: | |
| 278 | |
| 279 `'type'`: This should almost always be set to '<(library)', which allows | |
| 280 the user to define at gyp time whether libraries are to be built static | |
| 281 or shared. (On Linux, at least, linking with shared libraries saves | |
| 282 significant link time.) If it's necessary to pin down the type of | |
| 283 library to be built, the `type` can be set explicitly to | |
| 284 `static_library` or `shared_library`. | |
| 285 | |
| 286 `'direct_dependent_settings'`: This defines the settings that will be | |
| 287 applied to other targets that _directly depend_ on this target--that is, | |
| 288 that list _this_ target in their `'dependencies'` setting. This is | |
| 289 where you list the `defines`, `include_dirs`, `cflags` and `linkflags` | |
| 290 that other targets that compile or link against this target need to | |
| 291 build consistently. | |
| 292 | |
| 293 `'export_dependent_settings'`: This lists the targets whose | |
| 294 `direct_dependent_settings` should be "passed on" to other targets that | |
| 295 use (depend on) this target. `TODO: expand on this description.` | |
| 296 | |
| 297 ## Use Cases | |
| 298 | |
| 299 These use cases are intended to cover the most common actions performed | |
| 300 by developers using GYP. | |
| 301 | |
| 302 Note that these examples are _not_ fully-functioning, self-contained | |
| 303 examples (or else they'd be way too long). Each example mostly contains | |
| 304 just the keywords and settings relevant to the example, with perhaps a | |
| 305 few extra keywords for context. The intent is to try to show the | |
| 306 specific pieces you need to pay attention to when doing something. | |
| 307 [NOTE: if practical use shows that these examples are confusing without | |
| 308 additional context, please add what's necessary to clarify things.] | |
| 309 | |
| 310 ### Add new source files | |
| 311 | |
| 312 There are similar but slightly different patterns for adding a | |
| 313 platform-independent source file vs. adding a source file that only | |
| 314 builds on some of the supported platforms. | |
| 315 | |
| 316 #### Add a source file that builds on all platforms | |
| 317 | |
| 318 **Simplest possible case**: You are adding a file(s) that builds on all | |
| 319 platforms. | |
| 320 | |
| 321 Just add the file(s) to the `sources` list of the appropriate dictionary | |
| 322 in the `targets` list: | |
| 323 | |
| 324 ``` | |
| 325 { | |
| 326 'targets': [ | |
| 327 { | |
| 328 'target_name': 'my_target', | |
| 329 'type': 'executable', | |
| 330 'sources': [ | |
| 331 '../other/file_1.cc', | |
| 332 'new_file.cc', | |
| 333 'subdir/file3.cc', | |
| 334 ], | |
| 335 }, | |
| 336 ], | |
| 337 }, | |
| 338 ``` | |
| 339 | |
| 340 File path names are relative to the directory in which the `.gyp` file lives. | |
| 341 | |
| 342 Keep the list sorted alphabetically (unless there's a really, really, | |
| 343 _really_ good reason not to). | |
| 344 | |
| 345 #### Add a platform-specific source file | |
| 346 | |
| 347 ##### Your platform-specific file is named `*_linux.{ext}`, `*_mac.{ext}`, `*_po
six.{ext}` or `*_win.{ext}` | |
| 348 | |
| 349 The simplest way to add a platform-specific source file, assuming you're | |
| 350 adding a completely new file and get to name it, is to use one of the | |
| 351 following standard suffixes: | |
| 352 | |
| 353 * `_linux` (e.g. `foo_linux.cc`) | |
| 354 * `_mac` (e.g. `foo_mac.cc`) | |
| 355 * `_posix` (e.g. `foo_posix.cc`) | |
| 356 * `_win` (e.g. `foo_win.cc`) | |
| 357 | |
| 358 Simply add the file to the `sources` list of the appropriate dict within | |
| 359 the `targets` list, like you would any other source file. | |
| 360 | |
| 361 ``` | |
| 362 { | |
| 363 'targets': [ | |
| 364 { | |
| 365 'target_name': 'foo', | |
| 366 'type': 'executable', | |
| 367 'sources': [ | |
| 368 'independent.cc', | |
| 369 'specific_win.cc', | |
| 370 ], | |
| 371 }, | |
| 372 ], | |
| 373 }, | |
| 374 ``` | |
| 375 | |
| 376 The Chromium `.gyp` files all have appropriate `conditions` entries to | |
| 377 filter out the files that aren't appropriate for the current platform. | |
| 378 In the above example, the `specific_win.cc` file will be removed | |
| 379 automatically from the source-list on non-Windows builds. | |
| 380 | |
| 381 ##### Your platform-specific file does not use an already-defined pattern | |
| 382 | |
| 383 If your platform-specific file does not contain a | |
| 384 `*_{linux,mac,posix,win}` substring (or some other pattern that's | |
| 385 already in the `conditions` for the target), and you can't change the | |
| 386 file name, there are two patterns that can be used. | |
| 387 | |
| 388 **Prefererred**: Add the file to the `sources` list of the appropriate | |
| 389 dictionary within the `targets` list. Add an appropriate `conditions` | |
| 390 section to exclude the specific files name: | |
| 391 | |
| 392 ``` | |
| 393 { | |
| 394 'targets': [ | |
| 395 { | |
| 396 'target_name': 'foo', | |
| 397 'type': 'executable', | |
| 398 'sources': [ | |
| 399 'linux_specific.cc', | |
| 400 ], | |
| 401 'conditions': [ | |
| 402 ['OS != "linux"', { | |
| 403 'sources!': [ | |
| 404 # Linux-only; exclude on other platforms. | |
| 405 'linux_specific.cc', | |
| 406 ] | |
| 407 }[, | |
| 408 ], | |
| 409 }, | |
| 410 ], | |
| 411 }, | |
| 412 ``` | |
| 413 | |
| 414 Despite the duplicate listing, the above is generally preferred because | |
| 415 the `sources` list contains a useful global list of all sources on all | |
| 416 platforms with consistent sorting on all platforms. | |
| 417 | |
| 418 **Non-preferred**: In some situations, however, it might make sense to | |
| 419 list a platform-specific file only in a `conditions` section that | |
| 420 specifically _includes_ it in the `sources` list: | |
| 421 | |
| 422 ``` | |
| 423 { | |
| 424 'targets': [ | |
| 425 { | |
| 426 'target_name': 'foo', | |
| 427 'type': 'executable', | |
| 428 'sources': [], | |
| 429 ['OS == "linux"', { | |
| 430 'sources': [ | |
| 431 # Only add to sources list on Linux. | |
| 432 'linux_specific.cc', | |
| 433 ] | |
| 434 }], | |
| 435 }, | |
| 436 ], | |
| 437 }, | |
| 438 ``` | |
| 439 | |
| 440 The above two examples end up generating equivalent builds, with the | |
| 441 small exception that the `sources` lists will list the files in | |
| 442 different orders. (The first example defines explicitly where | |
| 443 `linux_specific.cc` appears in the list--perhaps in in the | |
| 444 middle--whereas the second example will always tack it on to the end of | |
| 445 the list.) | |
| 446 | |
| 447 **Including or excluding files using patterns**: There are more | |
| 448 complicated ways to construct a `sources` list based on patterns. See | |
| 449 `TODO(sgk)` below. | |
| 450 | |
| 451 ### Add a new executable | |
| 452 | |
| 453 An executable program is probably the most straightforward type of | |
| 454 target, since all it typically needs is a list of source files, some | |
| 455 compiler/linker settings (probably varied by platform), and some library | |
| 456 targets on which it depends and which must be used in the final link. | |
| 457 | |
| 458 #### Add an executable that builds on all platforms | |
| 459 | |
| 460 Add a dictionary defining the new executable target to the `targets` | |
| 461 list in the appropriate `.gyp` file. Example: | |
| 462 | |
| 463 ``` | |
| 464 { | |
| 465 'targets': [ | |
| 466 { | |
| 467 'target_name': 'new_unit_tests', | |
| 468 'type': 'executable', | |
| 469 'defines': [ | |
| 470 'FOO', | |
| 471 ], | |
| 472 'include_dirs': [ | |
| 473 '..', | |
| 474 ], | |
| 475 'dependencies': [ | |
| 476 'other_target_in_this_file', | |
| 477 'other_gyp2:target_in_other_gyp2', | |
| 478 ], | |
| 479 'sources': [ | |
| 480 'new_additional_source.cc', | |
| 481 'new_unit_tests.cc', | |
| 482 ], | |
| 483 }, | |
| 484 ], | |
| 485 } | |
| 486 ``` | |
| 487 | |
| 488 #### Add a platform-specific executable | |
| 489 | |
| 490 Add a dictionary defining the new executable target to the `targets` | |
| 491 list within an appropriate `conditions` block for the platform. The | |
| 492 `conditions` block should be a sibling to the top-level `targets` list: | |
| 493 | |
| 494 ``` | |
| 495 { | |
| 496 'targets': [ | |
| 497 ], | |
| 498 'conditions': [ | |
| 499 ['OS=="win"', { | |
| 500 'targets': [ | |
| 501 { | |
| 502 'target_name': 'new_unit_tests', | |
| 503 'type': 'executable', | |
| 504 'defines': [ | |
| 505 'FOO', | |
| 506 ], | |
| 507 'include_dirs': [ | |
| 508 '..', | |
| 509 ], | |
| 510 'dependencies': [ | |
| 511 'other_target_in_this_file', | |
| 512 'other_gyp2:target_in_other_gyp2', | |
| 513 ], | |
| 514 'sources': [ | |
| 515 'new_additional_source.cc', | |
| 516 'new_unit_tests.cc', | |
| 517 ], | |
| 518 }, | |
| 519 ], | |
| 520 }], | |
| 521 ], | |
| 522 } | |
| 523 ``` | |
| 524 | |
| 525 ### Add settings to a target | |
| 526 | |
| 527 There are several different types of settings that can be defined for | |
| 528 any given target. | |
| 529 | |
| 530 #### Add new preprocessor definitions (`-D` or `/D` flags) | |
| 531 | |
| 532 New preprocessor definitions are added by the `defines` setting: | |
| 533 | |
| 534 ``` | |
| 535 { | |
| 536 'targets': [ | |
| 537 { | |
| 538 'target_name': 'existing_target', | |
| 539 'defines': [ | |
| 540 'FOO', | |
| 541 'BAR=some_value', | |
| 542 ], | |
| 543 }, | |
| 544 ], | |
| 545 }, | |
| 546 ``` | |
| 547 | |
| 548 These may be specified directly in a target's settings, as in the above | |
| 549 example, or in a `conditions` section. | |
| 550 | |
| 551 #### Add a new include directory (`-I` or `/I` flags) | |
| 552 | |
| 553 New include directories are added by the `include_dirs` setting: | |
| 554 | |
| 555 ``` | |
| 556 { | |
| 557 'targets': [ | |
| 558 { | |
| 559 'target_name': 'existing_target', | |
| 560 'include_dirs': [ | |
| 561 '..', | |
| 562 'include', | |
| 563 ], | |
| 564 }, | |
| 565 ], | |
| 566 }, | |
| 567 ``` | |
| 568 | |
| 569 These may be specified directly in a target's settings, as in the above | |
| 570 example, or in a `conditions` section. | |
| 571 | |
| 572 #### Add new compiler flags | |
| 573 | |
| 574 Specific compiler flags can be added with the `cflags` setting: | |
| 575 | |
| 576 ``` | |
| 577 { | |
| 578 'targets': [ | |
| 579 { | |
| 580 'target_name': 'existing_target', | |
| 581 'conditions': [ | |
| 582 ['OS=="win"', { | |
| 583 'cflags': [ | |
| 584 '/WX', | |
| 585 ], | |
| 586 }, { # OS != "win" | |
| 587 'cflags': [ | |
| 588 '-Werror', | |
| 589 ], | |
| 590 }], | |
| 591 ], | |
| 592 }, | |
| 593 ], | |
| 594 }, | |
| 595 ``` | |
| 596 | |
| 597 Because these flags will be specific to the actual compiler involved, | |
| 598 they will almost always be only set within a `conditions` section. | |
| 599 | |
| 600 #### Add new linker flags | |
| 601 | |
| 602 Setting linker flags is OS-specific. On linux and most non-mac posix | |
| 603 systems, they can be added with the `ldflags` setting: | |
| 604 | |
| 605 ``` | |
| 606 { | |
| 607 'targets': [ | |
| 608 { | |
| 609 'target_name': 'existing_target', | |
| 610 'conditions': [ | |
| 611 ['OS=="linux"', { | |
| 612 'ldflags': [ | |
| 613 '-pthread', | |
| 614 ], | |
| 615 }], | |
| 616 ], | |
| 617 }, | |
| 618 ], | |
| 619 }, | |
| 620 ``` | |
| 621 | |
| 622 Because these flags will be specific to the actual linker involved, | |
| 623 they will almost always be only set within a `conditions` section. | |
| 624 | |
| 625 On OS X, linker settings are set via `xcode_settings`, on Windows via | |
| 626 `msvs_settings`. | |
| 627 | |
| 628 #### Exclude settings on a platform | |
| 629 | |
| 630 Any given settings keyword (`defines`, `include_dirs`, etc.) has a | |
| 631 corresponding form with a trailing `!` (exclamation point) to remove | |
| 632 values from a setting. One useful example of this is to remove the | |
| 633 Linux `-Werror` flag from the global settings defined in | |
| 634 `build/common.gypi`: | |
| 635 | |
| 636 ``` | |
| 637 { | |
| 638 'targets': [ | |
| 639 { | |
| 640 'target_name': 'third_party_target', | |
| 641 'conditions': [ | |
| 642 ['OS=="linux"', { | |
| 643 'cflags!': [ | |
| 644 '-Werror', | |
| 645 ], | |
| 646 }], | |
| 647 ], | |
| 648 }, | |
| 649 ], | |
| 650 }, | |
| 651 ``` | |
| 652 | |
| 653 ### Cross-compiling | |
| 654 | |
| 655 GYP has some (relatively limited) support for cross-compiling. | |
| 656 | |
| 657 If the variable `GYP_CROSSCOMPILE` or one of the toolchain-related | |
| 658 variables (like `CC_host` or `CC_target`) is set, GYP will think that | |
| 659 you wish to do a cross-compile. | |
| 660 | |
| 661 When cross-compiling, each target can be part of a "host" build, a | |
| 662 "target" build, or both. By default, the target is assumed to be (only) | |
| 663 part of the "target" build. The 'toolsets' property can be set on a | |
| 664 target to change the default. | |
| 665 | |
| 666 A target's dependencies are assumed to match the build type (so, if A | |
| 667 depends on B, by default that means that a target build of A depends on | |
| 668 a target build of B). You can explicitly depend on targets across | |
| 669 toolchains by specifying "#host" or "#target" in the dependencies list. | |
| 670 If GYP is not doing a cross-compile, the "#host" and "#target" will be | |
| 671 stripped as needed, so nothing breaks. | |
| 672 | |
| 673 ### Add a new library | |
| 674 | |
| 675 TODO: write intro | |
| 676 | |
| 677 #### Add a library that builds on all platforms | |
| 678 | |
| 679 Add the a dictionary defining the new library target to the `targets` | |
| 680 list in the appropriate `.gyp` file. Example: | |
| 681 | |
| 682 ``` | |
| 683 { | |
| 684 'targets': [ | |
| 685 { | |
| 686 'target_name': 'new_library', | |
| 687 'type': '<(library)', | |
| 688 'defines': [ | |
| 689 'FOO', | |
| 690 'BAR=some_value', | |
| 691 ], | |
| 692 'include_dirs': [ | |
| 693 '..', | |
| 694 ], | |
| 695 'dependencies': [ | |
| 696 'other_target_in_this_file', | |
| 697 'other_gyp2:target_in_other_gyp2', | |
| 698 ], | |
| 699 'direct_dependent_settings': { | |
| 700 'include_dirs': '.', | |
| 701 }, | |
| 702 'export_dependent_settings': [ | |
| 703 'other_target_in_this_file', | |
| 704 ], | |
| 705 'sources': [ | |
| 706 'new_additional_source.cc', | |
| 707 'new_library.cc', | |
| 708 ], | |
| 709 }, | |
| 710 ], | |
| 711 } | |
| 712 ``` | |
| 713 | |
| 714 The use of the `<(library)` variable above should be the default `type` | |
| 715 setting for most library targets, as it allows the developer to choose, | |
| 716 at `gyp` time, whether to build with static or shared libraries. | |
| 717 (Building with shared libraries saves a _lot_ of link time on Linux.) | |
| 718 | |
| 719 It may be necessary to build a specific library as a fixed type. Is so, | |
| 720 the `type` field can be hard-wired appropriately. For a static library: | |
| 721 | |
| 722 ``` | |
| 723 'type': 'static_library', | |
| 724 ``` | |
| 725 | |
| 726 For a shared library: | |
| 727 | |
| 728 ``` | |
| 729 'type': 'shared_library', | |
| 730 ``` | |
| 731 | |
| 732 #### Add a platform-specific library | |
| 733 | |
| 734 Add a dictionary defining the new library target to the `targets` list | |
| 735 within a `conditions` block that's a sibling to the top-level `targets` | |
| 736 list: | |
| 737 | |
| 738 ``` | |
| 739 { | |
| 740 'targets': [ | |
| 741 ], | |
| 742 'conditions': [ | |
| 743 ['OS=="win"', { | |
| 744 'targets': [ | |
| 745 { | |
| 746 'target_name': 'new_library', | |
| 747 'type': '<(library)', | |
| 748 'defines': [ | |
| 749 'FOO', | |
| 750 'BAR=some_value', | |
| 751 ], | |
| 752 'include_dirs': [ | |
| 753 '..', | |
| 754 ], | |
| 755 'dependencies': [ | |
| 756 'other_target_in_this_file', | |
| 757 'other_gyp2:target_in_other_gyp2', | |
| 758 ], | |
| 759 'direct_dependent_settings': { | |
| 760 'include_dirs': '.', | |
| 761 }, | |
| 762 'export_dependent_settings': [ | |
| 763 'other_target_in_this_file', | |
| 764 ], | |
| 765 'sources': [ | |
| 766 'new_additional_source.cc', | |
| 767 'new_library.cc', | |
| 768 ], | |
| 769 }, | |
| 770 ], | |
| 771 }], | |
| 772 ], | |
| 773 } | |
| 774 ``` | |
| 775 | |
| 776 ### Dependencies between targets | |
| 777 | |
| 778 GYP provides useful primitives for establishing dependencies between | |
| 779 targets, which need to be configured in the following situations. | |
| 780 | |
| 781 #### Linking with another library target | |
| 782 | |
| 783 ``` | |
| 784 { | |
| 785 'targets': [ | |
| 786 { | |
| 787 'target_name': 'foo', | |
| 788 'dependencies': [ | |
| 789 'libbar', | |
| 790 ], | |
| 791 }, | |
| 792 { | |
| 793 'target_name': 'libbar', | |
| 794 'type': '<(library)', | |
| 795 'sources': [ | |
| 796 ], | |
| 797 }, | |
| 798 ], | |
| 799 } | |
| 800 ``` | |
| 801 | |
| 802 Note that if the library target is in a different `.gyp` file, you have | |
| 803 to specify the path to other `.gyp` file, relative to this `.gyp` file's | |
| 804 directory: | |
| 805 | |
| 806 ``` | |
| 807 { | |
| 808 'targets': [ | |
| 809 { | |
| 810 'target_name': 'foo', | |
| 811 'dependencies': [ | |
| 812 '../bar/bar.gyp:libbar', | |
| 813 ], | |
| 814 }, | |
| 815 ], | |
| 816 } | |
| 817 ``` | |
| 818 | |
| 819 Adding a library often involves updating multiple `.gyp` files, adding | |
| 820 the target to the approprate `.gyp` file (possibly a newly-added `.gyp` | |
| 821 file), and updating targets in the other `.gyp` files that depend on | |
| 822 (link with) the new library. | |
| 823 | |
| 824 #### Compiling with necessary flags for a library target dependency | |
| 825 | |
| 826 We need to build a library (often a third-party library) with specific | |
| 827 preprocessor definitions or command-line flags, and need to ensure that | |
| 828 targets that depend on the library build with the same settings. This | |
| 829 situation is handled by a `direct_dependent_settings` block: | |
| 830 | |
| 831 ``` | |
| 832 { | |
| 833 'targets': [ | |
| 834 { | |
| 835 'target_name': 'foo', | |
| 836 'type': 'executable', | |
| 837 'dependencies': [ | |
| 838 'libbar', | |
| 839 ], | |
| 840 }, | |
| 841 { | |
| 842 'target_name': 'libbar', | |
| 843 'type': '<(library)', | |
| 844 'defines': [ | |
| 845 'LOCAL_DEFINE_FOR_LIBBAR', | |
| 846 'DEFINE_TO_USE_LIBBAR', | |
| 847 ], | |
| 848 'include_dirs': [ | |
| 849 '..', | |
| 850 'include/libbar', | |
| 851 ], | |
| 852 'direct_dependent_settings': { | |
| 853 'defines': [ | |
| 854 'DEFINE_TO_USE_LIBBAR', | |
| 855 ], | |
| 856 'include_dirs': [ | |
| 857 'include/libbar', | |
| 858 ], | |
| 859 }, | |
| 860 }, | |
| 861 ], | |
| 862 } | |
| 863 ``` | |
| 864 | |
| 865 In the above example, the sources of the `foo` executable will be | |
| 866 compiled with the options `-DDEFINE_TO_USE_LIBBAR -Iinclude/libbar`, | |
| 867 because of those settings' being listed in the | |
| 868 `direct_dependent_settings` block. | |
| 869 | |
| 870 Note that these settings will likely need to be replicated in the | |
| 871 settings for the library target itsef, so that the library will build | |
| 872 with the same options. This does not prevent the target from defining | |
| 873 additional options for its "internal" use when compiling its own source | |
| 874 files. (In the above example, these are the `LOCAL_DEFINE_FOR_LIBBAR` | |
| 875 define, and the `..` entry in the `include_dirs` list.) | |
| 876 | |
| 877 #### When a library depends on an additional library at final link time | |
| 878 | |
| 879 ``` | |
| 880 { | |
| 881 'targets': [ | |
| 882 { | |
| 883 'target_name': 'foo', | |
| 884 'type': 'executable', | |
| 885 'dependencies': [ | |
| 886 'libbar', | |
| 887 ], | |
| 888 }, | |
| 889 { | |
| 890 'target_name': 'libbar', | |
| 891 'type': '<(library)', | |
| 892 'dependencies': [ | |
| 893 'libother' | |
| 894 ], | |
| 895 'export_dependent_settings': [ | |
| 896 'libother' | |
| 897 ], | |
| 898 }, | |
| 899 { | |
| 900 'target_name': 'libother', | |
| 901 'type': '<(library)', | |
| 902 'direct_dependent_settings': { | |
| 903 'defines': [ | |
| 904 'DEFINE_FOR_LIBOTHER', | |
| 905 ], | |
| 906 'include_dirs': [ | |
| 907 'include/libother', | |
| 908 ], | |
| 909 }, | |
| 910 }, | |
| 911 ], | |
| 912 } | |
| 913 ``` | |
| 914 | |
| 915 ### Support for Mac OS X bundles | |
| 916 | |
| 917 gyp supports building bundles on OS X (.app, .framework, .bundle, etc). | |
| 918 Here is an example of this: | |
| 919 | |
| 920 ``` | |
| 921 { | |
| 922 'target_name': 'test_app', | |
| 923 'product_name': 'Test App Gyp', | |
| 924 'type': 'executable', | |
| 925 'mac_bundle': 1, | |
| 926 'sources': [ | |
| 927 'main.m', | |
| 928 'TestAppAppDelegate.h', | |
| 929 'TestAppAppDelegate.m', | |
| 930 ], | |
| 931 'mac_bundle_resources': [ | |
| 932 'TestApp/English.lproj/InfoPlist.strings', | |
| 933 'TestApp/English.lproj/MainMenu.xib', | |
| 934 ], | |
| 935 'link_settings': { | |
| 936 'libraries': [ | |
| 937 '$(SDKROOT)/System/Library/Frameworks/Cocoa.framework', | |
| 938 ], | |
| 939 }, | |
| 940 'xcode_settings': { | |
| 941 'INFOPLIST_FILE': 'TestApp/TestApp-Info.plist', | |
| 942 }, | |
| 943 }, | |
| 944 ``` | |
| 945 | |
| 946 The `mac_bundle` key tells gyp that this target should be a bundle. | |
| 947 `executable` targets get extension `.app` by default, `shared_library` | |
| 948 targets get `.framework` – but you can change the bundle extensions by | |
| 949 setting `product_extension` if you want. Files listed in | |
| 950 `mac_bundle_resources` will be copied to the bundle's `Resource` folder | |
| 951 of the bundle. You can also set | |
| 952 `process_outputs_as_mac_bundle_resources` to 1 in actions and rules to | |
| 953 let the output of actions and rules be added to that folder (similar to | |
| 954 `process_outputs_as_sources`). If `product_name` is not set, the bundle | |
| 955 will be named after `target_name`as usual. | |
| 956 | |
| 957 ### Move files (refactoring) | |
| 958 | |
| 959 TODO(sgk) | |
| 960 | |
| 961 ### Custom build steps | |
| 962 | |
| 963 TODO(sgk) | |
| 964 | |
| 965 #### Adding an explicit build step to generate specific files | |
| 966 | |
| 967 TODO(sgk) | |
| 968 | |
| 969 #### Adding a rule to handle files with a new suffix | |
| 970 | |
| 971 TODO(sgk) | |
| 972 | |
| 973 ### Build flavors | |
| 974 | |
| 975 TODO(sgk) | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1400043002:
Promote documents in md-pages branch. (Closed)
Base URL: https://chromium.googlesource.com/external/gyp@master