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 |