OLD | NEW |
(Empty) | |
| 1 # Input Format Reference |
| 2 |
| 3 [TOC] |
| 4 |
| 5 ## Primitive Types |
| 6 |
| 7 The following primitive types are found within input files: |
| 8 |
| 9 * String values, which may be represented by enclosing them in |
| 10 `'single quotes'` or `"double quotes"`. By convention, single |
| 11 quotes are used. |
| 12 * Integer values, which are represented in decimal without any special |
| 13 decoration. Integers are fairly rare in input files, but have a few |
| 14 applications in boolean contexts, where the convention is to |
| 15 represent true values with `1` and false with `0`. |
| 16 * Lists, which are represented as a sequence of items separated by |
| 17 commas (`,`) within square brackets (`[` and `]`). A list may |
| 18 contain any other primitive types, including other lists. |
| 19 Generally, each item of a list must be of the same type as all other |
| 20 items in the list, but in some cases (such as within `conditions` |
| 21 sections), the list structure is more tightly specified. A trailing |
| 22 comma is permitted. |
| 23 |
| 24 This example list contains three string values. |
| 25 |
| 26 ``` |
| 27 [ 'Generate', 'Your', 'Projects', ] |
| 28 ``` |
| 29 |
| 30 * Dictionaries, which map keys to values. All keys are strings. |
| 31 Values may be of any other primitive type, including other |
| 32 dictionaries. A dictionary is enclosed within curly braces (`{` and |
| 33 `}`). Keys precede values, separated by a colon (`:`). Successive |
| 34 dictionary entries are separated by commas (`,`). A trailing comma |
| 35 is permitted. It is an error for keys to be duplicated within a |
| 36 single dictionary as written in an input file, although keys may |
| 37 replace other keys during [merging](#Merging). |
| 38 |
| 39 This example dictionary maps each of three keys to different values. |
| 40 |
| 41 ``` |
| 42 { |
| 43 'inputs': ['version.c.in'], |
| 44 'outputs': ['version.c'], |
| 45 'process_outputs_as_sources': 1, |
| 46 } |
| 47 ``` |
| 48 |
| 49 ## Overall Structure |
| 50 |
| 51 A GYP input file is organized as structured data. At the root scope of |
| 52 each `.gyp` or `.gypi` (include) file is a dictionary. The keys and |
| 53 values of this dictionary, along with any descendants contained within |
| 54 the values, provide the data contained within the file. This data is |
| 55 given meaning by interpreting specific key names and their associated |
| 56 values in specific ways (see [Settings Keys](#Settings_Keys)). |
| 57 |
| 58 ### Comments (#) |
| 59 |
| 60 Within an input file, a comment is introduced by a pound sign (`#`) not |
| 61 within a string. Any text following the pound sign, up until the end of |
| 62 the line, is treated as a comment. |
| 63 |
| 64 #### Example |
| 65 |
| 66 ``` |
| 67 { |
| 68 'school_supplies': [ |
| 69 'Marble composition book', |
| 70 'Sharp #2 pencil', |
| 71 'Safety scissors', # You still shouldn't run with these |
| 72 ], |
| 73 } |
| 74 ``` |
| 75 |
| 76 In this example, the # in `'Sharp #2 pencil'` is not taken as |
| 77 introducing a comment because it occurs within a string, but the text |
| 78 after `'Safety scissors'` is treated as a comment having no impact on |
| 79 the data within the file. |
| 80 |
| 81 ## Merging |
| 82 |
| 83 ### Merge Basics (=, ?, +) |
| 84 |
| 85 Many operations on GYP input files occurs by merging dictionary and list |
| 86 items together. During merge operations, it is important to recognize |
| 87 the distinction between source and destination values. Items from the |
| 88 source value are merged into the destination, which leaves the source |
| 89 unchanged and the destination modified by the source. A dictionary may |
| 90 only be merged into another dictionary, and a list may only be merged |
| 91 into another list. |
| 92 |
| 93 * When merging a dictionary, for each key in the source: |
| 94 * If the key does not exist in the destination dictionary, insert it |
| 95 and copy the associated value directly. |
| 96 * If the key does exist: |
| 97 * If the associated value is a dictionary, perform the dictionary |
| 98 merging procedure using the source's and destination's value |
| 99 dictionaries. |
| 100 * If the associated value is a list, perform the list merging |
| 101 procedure using the source's and destination's value lists. |
| 102 * If the associated value is a string or integer, the destination |
| 103 value is replaced by the source value. |
| 104 * When merging a list, merge according to the suffix appended to the |
| 105 key name, if the list is a value within a dictionary. |
| 106 * If the key ends with an equals sign (`=`), the policy is for the |
| 107 source list to completely replace the destination list if it |
| 108 exists. _Mnemonic: `=` for assignment._ |
| 109 * If the key ends with a question mark (`?`), the policy is for the |
| 110 source list to be set as the destination list only if the key is |
| 111 not already present in the destination. _Mnemonic: `?` for |
| 112 conditional assignment_. |
| 113 * If the key ends with a plus sign (`+`), the policy is for the |
| 114 source list contents to be prepended to the destination list. |
| 115 _Mnemonic: `+` for addition or concatenation._ |
| 116 * If the list key is undecorated, the policy is for the source list |
| 117 contents to be appended to the destination list. This is the |
| 118 default list merge policy. |
| 119 |
| 120 #### Example |
| 121 |
| 122 Source dictionary: |
| 123 |
| 124 ``` |
| 125 { |
| 126 'include_dirs+': [ |
| 127 'shared_stuff/public', |
| 128 ], |
| 129 'link_settings': { |
| 130 'libraries': [ |
| 131 '-lshared_stuff', |
| 132 ], |
| 133 }, |
| 134 'test': 1, |
| 135 } |
| 136 ``` |
| 137 |
| 138 Destination dictionary: |
| 139 |
| 140 ``` |
| 141 { |
| 142 'target_name': 'hello', |
| 143 'sources': [ |
| 144 'kitty.cc', |
| 145 ], |
| 146 'include_dirs': [ |
| 147 'headers', |
| 148 ], |
| 149 'link_settings': { |
| 150 'libraries': [ |
| 151 '-lm', |
| 152 ], |
| 153 'library_dirs': [ |
| 154 '/usr/lib', |
| 155 ], |
| 156 }, |
| 157 'test': 0, |
| 158 } |
| 159 ``` |
| 160 |
| 161 Merged dictionary: |
| 162 |
| 163 ``` |
| 164 { |
| 165 'target_name': 'hello', |
| 166 'sources': [ |
| 167 'kitty.cc', |
| 168 ], |
| 169 'include_dirs': [ |
| 170 'shared_stuff/public', # Merged, list item prepended due to include_dirs+ |
| 171 'headers', |
| 172 ], |
| 173 'link_settings': { |
| 174 'libraries': [ |
| 175 '-lm', |
| 176 '-lshared_stuff', # Merged, list item appended |
| 177 ], |
| 178 'library_dirs': [ |
| 179 '/usr/lib', |
| 180 ], |
| 181 }, |
| 182 'test': 1, # Merged, int value replaced |
| 183 } |
| 184 ``` |
| 185 |
| 186 ## Pathname Relativization |
| 187 |
| 188 In a `.gyp` or `.gypi` file, many string values are treated as pathnames |
| 189 relative to the file in which they are defined. |
| 190 |
| 191 String values associated with the following keys, or contained within |
| 192 lists associated with the following keys, are treated as pathnames: |
| 193 |
| 194 * destination |
| 195 * files |
| 196 * include\_dirs |
| 197 * inputs |
| 198 * libraries |
| 199 * outputs |
| 200 * sources |
| 201 * mac\_bundle\_resources |
| 202 * mac\_framework\_dirs |
| 203 * msvs\_cygwin\_dirs |
| 204 * msvs\_props |
| 205 |
| 206 Additionally, string values associated with keys ending in the following |
| 207 suffixes, or contained within lists associated with keys ending in the |
| 208 following suffixes, are treated as pathnames: |
| 209 |
| 210 * `_dir` |
| 211 * `_dirs` |
| 212 * `_file` |
| 213 * `_files` |
| 214 * `_path` |
| 215 * `_paths` |
| 216 |
| 217 However, any string value beginning with any of these characters is |
| 218 excluded from pathname relativization: |
| 219 |
| 220 * `/` for identifying absolute paths. |
| 221 * `$` for introducing build system variable expansions. |
| 222 * `-` to support specifying such items as `-llib`, meaning “library |
| 223 `lib` in the library search path.” |
| 224 * `<`, `>`, and `!` for GYP expansions. |
| 225 |
| 226 When merging such relative pathnames, they are adjusted so that they can |
| 227 remain valid relative pathnames, despite being relative to a new home. |
| 228 |
| 229 #### Example |
| 230 |
| 231 Source dictionary from `../build/common.gypi`: |
| 232 |
| 233 ``` |
| 234 { |
| 235 'include_dirs': ['include'], # Treated as relative to ../build |
| 236 'libraries': ['-lz'], # Not treated as a pathname, begins with a dash |
| 237 'defines': ['NDEBUG'], # defines does not contain pathnames |
| 238 } |
| 239 ``` |
| 240 |
| 241 Target dictionary, from `base.gyp`: |
| 242 |
| 243 ``` |
| 244 { |
| 245 'sources': ['string_util.cc'], |
| 246 } |
| 247 ``` |
| 248 |
| 249 Merged dictionary: |
| 250 |
| 251 ``` |
| 252 { |
| 253 'sources': ['string_util.cc'], |
| 254 'include_dirs': ['../build/include'], |
| 255 'libraries': ['-lz'], |
| 256 'defines': ['NDEBUG'], |
| 257 } |
| 258 ``` |
| 259 |
| 260 Because of pathname relativization, after the merge is complete, all of |
| 261 the pathnames in the merged dictionary are valid relative to the |
| 262 directory containing `base.gyp`. |
| 263 |
| 264 ## List Singletons |
| 265 |
| 266 Some list items are treated as singletons, and the list merge process |
| 267 will enforce special rules when merging them. At present, any string |
| 268 item in a list that does not begin with a dash (`-`) is treated as a |
| 269 singleton, although **this is subject to change.** When appending or |
| 270 prepending a singleton to a list, if the item is already in the list, |
| 271 only the earlier instance is retained in the merged list. |
| 272 |
| 273 #### Example |
| 274 |
| 275 Source dictionary: |
| 276 |
| 277 ``` |
| 278 { |
| 279 'defines': [ |
| 280 'EXPERIMENT=1', |
| 281 'NDEBUG', |
| 282 ], |
| 283 } |
| 284 ``` |
| 285 |
| 286 Destination dictionary: |
| 287 |
| 288 ``` |
| 289 { |
| 290 'defines': [ |
| 291 'NDEBUG', |
| 292 'USE_THREADS', |
| 293 ], |
| 294 } |
| 295 ``` |
| 296 |
| 297 Merged dictionary: |
| 298 |
| 299 ``` |
| 300 { |
| 301 'defines': [ |
| 302 'NDEBUG', |
| 303 'USE_THREADS', |
| 304 'EXPERIMENT=1', # Note that NDEBUG is not appended after this. |
| 305 ], |
| 306 } |
| 307 ``` |
| 308 |
| 309 ## Including Other Files |
| 310 |
| 311 If the `-I` (`--include`) argument was used to invoke GYP, any files |
| 312 specified will be implicitly merged into the root dictionary of all |
| 313 `.gyp` files. |
| 314 |
| 315 An [includes](#includes) section may be placed anywhere within a |
| 316 `.gyp` or `.gypi` (include) file. `includes` sections contain lists of |
| 317 other files to include. They are processed sequentially and merged into |
| 318 the enclosing dictionary at the point that the `includes` section was |
| 319 found. `includes` sections at the root of a `.gyp` file dictionary are |
| 320 merged after any `-I` includes from the command line. |
| 321 |
| 322 [includes](#includes) sections are processed immediately after a file is |
| 323 loaded, even before [variable and conditional |
| 324 processing](#Variables_and_Conditionals), so it is not possible to |
| 325 include a file based on a [variable reference](#Variable_Expansions). |
| 326 While it would be useful to be able to include files based on variable |
| 327 expansions, it is most likely more useful to allow included files access |
| 328 to variables set by the files that included them. |
| 329 |
| 330 An [includes](#includes) section may, however, be placed within a |
| 331 [conditional](#Conditionals) section. The included file itself will |
| 332 be loaded unconditionally, but its dictionary will be discarded if the |
| 333 associated condition is not true. |
| 334 |
| 335 ## Variables and Conditionals |
| 336 |
| 337 ### Variables |
| 338 |
| 339 There are three main types of variables within GYP. |
| 340 |
| 341 * Predefined variables. By convention, these are named with |
| 342 `CAPITAL_LETTERS`. Predefined variables are set automatically by |
| 343 GYP. They may be overridden, but it is not advisable to do so. See |
| 344 [Predefined Variables](#Predefined_Variables) for a list of |
| 345 variables that GYP provides. |
| 346 * User-defined variables. Within any dictionary, a key named |
| 347 `variables` can be provided, containing a mapping between variable |
| 348 names (keys) and their contents (values), which may be strings, |
| 349 integers, or lists of strings. By convention, user-defined |
| 350 variables are named with `lowercase_letters`. |
| 351 * Automatic variables. Within any dictionary, any key with a string |
| 352 value has a corresponding automatic variable whose name is the same |
| 353 as the key name with an underscore (`_`) prefixed. For example, if |
| 354 your dictionary contains `type: 'static_library'`, an automatic |
| 355 variable named `_type` will be provided, and its value will be a |
| 356 string, `'static_library'`. |
| 357 |
| 358 Variables are inherited from enclosing scopes. |
| 359 |
| 360 ### Providing Default Values for Variables (%) |
| 361 |
| 362 Within a `variables` section, keys named with percent sign (`%`) |
| 363 suffixes mean that the variable should be set only if it is undefined at |
| 364 the time it is processed. This can be used to provide defaults for |
| 365 variables that would otherwise be undefined, so that they may reliably |
| 366 be used in [variable expansion or conditional |
| 367 processing](#Variables_and_Conditionals). |
| 368 |
| 369 ### Predefined Variables |
| 370 |
| 371 Each GYP generator module provides defaults for the following variables: |
| 372 |
| 373 * `OS`: The name of the operating system that the generator produces |
| 374 output for. Common values for values for `OS` are: |
| 375 |
| 376 * `'linux'` |
| 377 * `'mac'` |
| 378 * `'win'` |
| 379 |
| 380 But other values may be encountered and this list should not be |
| 381 considered exhaustive. The `gypd` (debug) generator module does not |
| 382 provide a predefined value for `OS`. When invoking GYP with the |
| 383 `gypd` module, if a value for `OS` is needed, it must be provided on |
| 384 the command line, such as `gyp -f gypd -DOS=mac`. |
| 385 |
| 386 GYP generators also provide defaults for these variables. They may |
| 387 be expressed in terms of variables used by the build system that |
| 388 they generate for, often in `$(VARIABLE)` format. For example, the |
| 389 GYP `PRODUCT_DIR` variable maps to the Xcode `BUILT_PRODUCTS_DIR` |
| 390 variable, so `PRODUCT_DIR` is defined by the Xcode generator as |
| 391 `$(BUILT_PRODUCTS_DIR)`. |
| 392 * `EXECUTABLE_PREFIX`: A prefix, if any, applied to executable names. |
| 393 Usually this will be an empty string. |
| 394 * `EXECUTABLE_SUFFIX`: A suffix, if any, applied to executable names. |
| 395 On Windows, this will be `.exe`, elsewhere, it will usually be an |
| 396 empty string. |
| 397 * `INTERMEDIATE_DIR`: A directory that can be used to place |
| 398 intermediate build results in. `INTERMEDIATE_DIR` is only |
| 399 guaranteed to be accessible within a single target (See targets). |
| 400 This variable is most useful within the context of rules and actions |
| 401 (See rules, See actions). Compare with `SHARED_INTERMEDIATE_DIR`. |
| 402 * `PRODUCT_DIR`: The directory in which the primary output of each |
| 403 target, such as executables and libraries, is placed. |
| 404 * `RULE_INPUT_ROOT`: The base name for the input file (e.g. "`foo`"). |
| 405 See Rules. |
| 406 * `RULE_INPUT_EXT`: The file extension for the input file (e.g. |
| 407 "`.cc`"). See Rules. |
| 408 * `RULE_INPUT_NAME`: Full name of the input file (e.g. "`foo.cc`"). |
| 409 See Rules. |
| 410 * `RULE_INPUT_PATH`: Full path to the input file (e.g. |
| 411 "`/bar/foo.cc`"). See Rules. |
| 412 * `SHARED_INTERMEDIATE_DIR`: A directory that can be used to place |
| 413 intermediate build results in, and have them be accessible to other |
| 414 targets. Unlike `INTERMEDIATE_DIR`, each target in a project, |
| 415 possibly spanning multiple `.gyp` files, shares the same |
| 416 `SHARED_INTERMEDIATE_DIR`. |
| 417 |
| 418 The following additional predefined variables may be available under |
| 419 certain circumstances: |
| 420 |
| 421 * `DEPTH`. When GYP is invoked with a `--depth` argument, when |
| 422 processing any `.gyp` file, `DEPTH` will be a relative path from the |
| 423 `.gyp` file to the directory specified by the `--depth` argument. |
| 424 |
| 425 ### User-Defined Variables |
| 426 |
| 427 A user-defined variable may be defined in terms of other variables, but |
| 428 not other variables that have definitions provided in the same scope. |
| 429 |
| 430 ### Variable Expansions (<, >, <@, >@) |
| 431 |
| 432 GYP provides two forms of variable expansions, “early” or “pre” |
| 433 expansions, and “late,” “post,” or “target” expansions. They have |
| 434 similar syntax, differing only in the character used to introduce them. |
| 435 |
| 436 * Early expansions are introduced by a less-than (`<`) character. |
| 437 _Mnemonic: the arrow points to the left, earlier on a timeline._ |
| 438 * Late expansions are introduced by a less-than (`>`) character. |
| 439 _Mnemonic: the arrow points to the right, later on a timeline._ |
| 440 |
| 441 The difference the two phases of expansion is described in [Early and |
| 442 Late Phases](#Early_and_Late_Phases). |
| 443 |
| 444 These characters were chosen based upon the requirement that they not |
| 445 conflict with the variable format used natively by build systems. While |
| 446 the dollar sign (`$`) is the most natural fit for variable expansions, |
| 447 its use was ruled out because most build systems already use that |
| 448 character for their own variable expansions. Using different characters |
| 449 means that no escaping mechanism was needed to differentiate between GYP |
| 450 variables and build system variables, and writing build system variables |
| 451 into GYP files is not cumbersome. |
| 452 |
| 453 Variables may contain lists or strings, and variable expansions may |
| 454 occur in list or string context. There are variant forms of variable |
| 455 expansions that may be used to determine how each type of variable is to |
| 456 be expanded in each context. |
| 457 |
| 458 * When a variable is referenced by `<(VAR)` or `>(VAR)`: |
| 459 * If `VAR` is a string, the variable reference within the string is |
| 460 replaced by variable's string value. |
| 461 * If `VAR` is a list, the variable reference within the string is |
| 462 replaced by a string containing the concatenation of all of the |
| 463 variable’s list items. Generally, the items are joined with |
| 464 spaces between each, but the specific behavior is |
| 465 generator-specific. The precise encoding used by any generator |
| 466 should be one that would allow each list item to be treated as a |
| 467 separate argument when used as program arguments on the system |
| 468 that the generator produces output for. |
| 469 * When a variable is referenced by `<@(VAR)` or `>@(VAR)`: |
| 470 * The expansion must occur in list context. |
| 471 * The list item must be `'<@(VAR)'` or `'>@(VAR)'` exactly. |
| 472 * If `VAR` is a list, each of its elements are inserted into the |
| 473 list in which expansion is taking place, replacing the list item |
| 474 containing the variable reference. |
| 475 * If `VAR` is a string, the string is converted to a list which is |
| 476 inserted into the list in which expansion is taking place as |
| 477 above. The conversion into a list is generator-specific, but |
| 478 generally, spaces in the string are taken as separators between |
| 479 list items. The specific method of converting the string to a |
| 480 list should be the inverse of the encoding method used to expand |
| 481 list variables in string context, above. |
| 482 |
| 483 GYP treats references to undefined variables as errors. |
| 484 |
| 485 ### Command Expansions (<!, <!@) |
| 486 |
| 487 Command expansions function similarly to variable expansions, but |
| 488 instead of resolving variable references, they cause GYP to execute a |
| 489 command at generation time and use the command’s output as the |
| 490 replacement. Command expansions are introduced by a less than and |
| 491 exclamation mark (`<!`). |
| 492 |
| 493 In a command expansion, the entire string contained within the |
| 494 parentheses is passed to the system’s shell. The command’s output is |
| 495 assigned to a string value that may subsequently be expanded in list |
| 496 context in the same way as variable expansions if an `@` character is |
| 497 used. |
| 498 |
| 499 In addition, command expansions (unlike other variable expansions) may |
| 500 include nested variable expansions. So something like this is allowed: |
| 501 |
| 502 ``` |
| 503 'variables' : [ |
| 504 'foo': '<!(echo Build Date <!(date))', |
| 505 ], |
| 506 ``` |
| 507 |
| 508 expands to: |
| 509 |
| 510 ``` |
| 511 'variables' : [ |
| 512 'foo': 'Build Date 02:10:38 PM Fri Jul 24, 2009 -0700 PDT', |
| 513 ], |
| 514 ``` |
| 515 |
| 516 You may also put commands into arrays in order to quote arguments (but |
| 517 note that you need to use a different string quoting character): |
| 518 |
| 519 ``` |
| 520 'variables' : [ |
| 521 'files': '<!(["ls", "-1", "Filename With Spaces"])', |
| 522 ], |
| 523 ``` |
| 524 |
| 525 GYP treats command failures (as indicated by a nonzero exit status) |
| 526 during command expansion as errors. |
| 527 |
| 528 #### Example |
| 529 |
| 530 ``` |
| 531 { |
| 532 'sources': [ |
| 533 '!(echo filename with space.cc)', |
| 534 ], |
| 535 'libraries': [ |
| 536 '!@(pkg-config --libs-only-l apr-1)', |
| 537 ], |
| 538 } |
| 539 ``` |
| 540 |
| 541 might expand to: |
| 542 |
| 543 ``` |
| 544 { |
| 545 'sources': [ |
| 546 'filename with space.cc', # no @, expands into a single string |
| 547 ], |
| 548 'libraries': [ # @ was used, so there's a separate list item for each lib |
| 549 '-lapr-1', |
| 550 '-lpthread', |
| 551 ], |
| 552 } |
| 553 ``` |
| 554 |
| 555 ## Conditionals |
| 556 |
| 557 Conditionals use the same set of variables used for variable expansion. |
| 558 As with variable expansion, there are two phases of conditional |
| 559 evaluation: |
| 560 |
| 561 * “Early” or “pre” conditional evaluation, introduced in |
| 562 [conditions](#conditions) sections. |
| 563 * “Late,” “post,” or “target” conditional evaluation, introduced in |
| 564 [target\_conditions](#target_conditions) sections. |
| 565 |
| 566 The syntax for each type is identical, they differ only in the key name |
| 567 used to identify them and the timing of their evaluation. A more |
| 568 complete description of syntax and use is provided in |
| 569 [conditions](#conditions). |
| 570 |
| 571 The difference the two phases of evaluation is described in [Early and |
| 572 Late Phases](#Early_and_Late_Phases). |
| 573 |
| 574 ## Timing of Variable Expansion and Conditional Evaluation |
| 575 |
| 576 ### Early and Late Phases |
| 577 |
| 578 GYP performs two phases of variable expansion and conditional evaluation: |
| 579 |
| 580 * The “early” or “pre” phase operates on [conditions](#conditions) |
| 581 sections and the `<` form of [variable |
| 582 expansions](#Variable_Expansions). |
| 583 * The “late,” “post,” or “target” phase operates on |
| 584 [target\_conditions](#target_conditions) sections, the `>` form |
| 585 of [variable expansions](#Variable_Expansions), |
| 586 and on the `!` form of [command |
| 587 expansions](#Command_Expansions_(!,_!@)). |
| 588 |
| 589 These two phases are provided because there are some circumstances in |
| 590 which each is desirable. |
| 591 |
| 592 The “early” phase is appropriate for most expansions and evaluations. |
| 593 “Early” expansions and evaluations may be performed anywhere within any |
| 594 `.gyp` or `.gypi` file. |
| 595 |
| 596 The “late” phase is appropriate when expansion or evaluation must be |
| 597 deferred until a specific section has been merged into target context. |
| 598 “Late” expansions and evaluations only occur within `targets` sections |
| 599 and their descendants. The typical use case for a late-phase expansion |
| 600 is to provide, in some globally-included `.gypi` file, distinct |
| 601 behaviors depending on the specifics of a target. |
| 602 |
| 603 #### Example |
| 604 |
| 605 Given this input: |
| 606 |
| 607 ``` |
| 608 { |
| 609 'target_defaults': { |
| 610 'target_conditions': [ |
| 611 ['_type=="shared_library"', {'cflags': ['-fPIC']}], |
| 612 ], |
| 613 }, |
| 614 'targets': [ |
| 615 { |
| 616 'target_name': 'sharing_is_caring', |
| 617 'type': 'shared_library', |
| 618 }, |
| 619 { |
| 620 'target_name': 'static_in_the_attic', |
| 621 'type': 'static_library', |
| 622 }, |
| 623 ] |
| 624 } |
| 625 ``` |
| 626 |
| 627 The conditional needs to be evaluated only in target context; it is |
| 628 nonsense outside of target context because no `_type` variable is |
| 629 defined. [target\_conditions](#target_conditions) allows evaluation |
| 630 to be deferred until after the [targets](#targets) sections are |
| 631 merged into their copies of [target\_defaults](#target_defaults). |
| 632 The resulting targets, after “late” phase processing: |
| 633 |
| 634 ``` |
| 635 { |
| 636 'targets': [ |
| 637 { |
| 638 'target_name': 'sharing_is_caring', |
| 639 'type': 'shared_library', |
| 640 'cflags': ['-fPIC'], |
| 641 }, |
| 642 { |
| 643 'target_name': 'static_in_the_attic', |
| 644 'type': 'static_library', |
| 645 }, |
| 646 ] |
| 647 } |
| 648 ``` |
| 649 |
| 650 ### Expansion and Evaluation Performed Simultaneously |
| 651 |
| 652 During any expansion and evaluation phase, both expansion and evaluation |
| 653 are performed simultaneously. The process for handling variable |
| 654 expansions and conditional evaluation within a dictionary is: |
| 655 |
| 656 * Load [automatic variables](#Variables) (those with leading |
| 657 underscores). |
| 658 * If a [variables](#variables) section is present, recurse into its |
| 659 dictionary. This allows [conditionals](#Conditionals) to be |
| 660 present within the `variables` dictionary. |
| 661 * Load [Variables user-defined variables](#User-Defined) from the |
| 662 [variables](#variables) section. |
| 663 * For each string value in the dictionary, perform [variable |
| 664 expansion](#Variable_Expansions) and, if operating |
| 665 during the “late” phase, [command |
| 666 expansions](#Command_Expansions). |
| 667 * Reload [automatic variables](#Variables) and [Variables |
| 668 user-defined variables](#User-Defined) because the variable |
| 669 expansion step may have resulted in changes to the automatic |
| 670 variables. |
| 671 * If a [conditions](#conditions) or |
| 672 [target\_conditions](#target_conditions) section (depending on |
| 673 phase) is present, recurse into its dictionary. This is done after |
| 674 variable expansion so that conditionals may take advantage of |
| 675 expanded automatic variables. |
| 676 * Evaluate [conditionals](#Conditionals). |
| 677 * Reload [automatic variables](#Variables) and [Variables |
| 678 user-defined variables](#User-Defined) because the conditional |
| 679 evaluation step may have resulted in changes to the automatic |
| 680 variables. |
| 681 * Recurse into child dictionaries or lists that have not yet been |
| 682 processed. |
| 683 |
| 684 One quirk of this ordering is that you cannot expect a |
| 685 [variables](#variables) section within a dictionary’s |
| 686 [conditional](#Conditionals) to be effective in the dictionary |
| 687 itself, but the added variables will be effective in any child |
| 688 dictionaries or lists. It is thought to be far more worthwhile to |
| 689 provide resolved [automatic variables](#Variables) to |
| 690 [conditional](#Conditionals) sections, though. As a workaround, to |
| 691 conditionalize variable values, place a [conditions](#conditions) or |
| 692 [target\_conditions](#target_conditions) section within the |
| 693 [variables](#variables) section. |
| 694 |
| 695 ## Dependencies and Dependents |
| 696 |
| 697 In GYP, “dependents” are targets that rely on other targets, called |
| 698 “dependencies.” Dependents declare their reliance with a special |
| 699 section within their target dictionary, |
| 700 [dependencies](#dependencies). |
| 701 |
| 702 ### Dependent Settings |
| 703 |
| 704 It is useful for targets to “advertise” settings to their dependents. |
| 705 For example, a target might require that all of its dependents add |
| 706 certain directories to their include paths, link against special |
| 707 libraries, or define certain preprocessor macros. GYP allows these |
| 708 cases to be handled gracefully with “dependent settings” sections. |
| 709 There are three types of such sections: |
| 710 |
| 711 * [direct\_dependent\_settings](#direct_dependent_settings), which |
| 712 advertises settings to a target's direct dependents only. |
| 713 * [all\_dependent\_settings](#all_dependnet_settings), which |
| 714 advertises settings to all of a target's dependents, both direct and |
| 715 indirect. |
| 716 * [link\_settings](#link_settings), which contains settings that |
| 717 should be applied when a target’s object files are used as linker |
| 718 input. |
| 719 |
| 720 Furthermore, in some cases, a target needs to pass its dependencies’ |
| 721 settings on to its own dependents. This might happen when a target’s |
| 722 own public header files include header files provided by its dependency. |
| 723 [export\_dependent\_settings](#export_dependent_settings) allows a |
| 724 target to declare dependencies for which |
| 725 [direct\_dependent\_settings](#direct_dependent_settings) should be |
| 726 passed through to its own dependents. |
| 727 |
| 728 Dependent settings processing merges a copy of the relevant dependent |
| 729 settings dictionary from a dependency into its relevant dependent |
| 730 targets. |
| 731 |
| 732 In most instances, |
| 733 [direct\_dependent\_settings](#direct_dependent_settings) will be |
| 734 used. There are very few cases where |
| 735 [all\_dependent\_settings](#all_dependent_settings) is actually |
| 736 correct; in most of the cases where it is tempting to use, it would be |
| 737 preferable to declare |
| 738 [export\_dependent\_settings](#export_dependent_settings). Most |
| 739 [libraries](#libraries) and [library\_dirs](#library_dirs) |
| 740 sections should be placed within [link\_settings](#link_settings) |
| 741 sections. |
| 742 |
| 743 #### Example |
| 744 |
| 745 Given: |
| 746 |
| 747 ``` |
| 748 { |
| 749 'targets': [ |
| 750 { |
| 751 'target_name': 'cruncher', |
| 752 'type': 'static_library', |
| 753 'sources': ['cruncher.cc'], |
| 754 'direct_dependent_settings': { |
| 755 'include_dirs': ['.'], # dependents need to find cruncher.h. |
| 756 }, |
| 757 'link_settings': { |
| 758 'libraries': ['-lm'], # cruncher.cc does math. |
| 759 }, |
| 760 }, |
| 761 { |
| 762 'target_name': 'cruncher_test', |
| 763 'type': 'executable', |
| 764 'dependencies': ['cruncher'], |
| 765 'sources': ['cruncher_test.cc'], |
| 766 }, |
| 767 ], |
| 768 } |
| 769 ``` |
| 770 |
| 771 After dependent settings processing, the dictionary for `cruncher_test` |
| 772 will be: |
| 773 |
| 774 ``` |
| 775 { |
| 776 'target_name': 'cruncher_test', |
| 777 'type': 'executable', |
| 778 'dependencies': ['cruncher'], # implies linking against cruncher |
| 779 'sources': ['cruncher_test.cc'], |
| 780 'include_dirs': ['.'] |
| 781 'libraries': ['-lm'], |
| 782 }, |
| 783 ``` |
| 784 |
| 785 If `cruncher` was declared as a `shared_library` instead of a |
| 786 `static_library`, the `cruncher_test` target would not contain `-lm`, |
| 787 but instead, `cruncher` itself would link against `-lm`. |
| 788 |
| 789 ## Linking Dependencies |
| 790 |
| 791 The precise meaning of a dependency relationship varies with the |
| 792 [types](#type) of the [targets](#targets) at either end of the |
| 793 relationship. In GYP, a dependency relationship can indicate two things |
| 794 about how targets relate to each other: |
| 795 |
| 796 * Whether the dependent target needs to link against the dependency. |
| 797 * Whether the dependency target needs to be built prior to the |
| 798 dependent. If the former case is true, this case must be true as |
| 799 well. |
| 800 |
| 801 The analysis of the first item is complicated by the differences between |
| 802 static and shared libraries. |
| 803 |
| 804 * Static libraries are simply collections of object files (`.o` or |
| 805 `.obj`) that are used as inputs to a linker (`ld` or `link.exe`). |
| 806 Static libraries don't link against other libraries, they’re |
| 807 collected together and used when eventually linking a shared library |
| 808 or executable. |
| 809 * Shared libraries are linker output and must undergo symbol |
| 810 resolution. They must link against other libraries (static or |
| 811 shared) in order to facilitate symbol resolution. They may be used |
| 812 as libraries in subsequent link steps. |
| 813 * Executables are also linker output, and also undergo symbol |
| 814 resolution. Like shared libraries, they must link against static |
| 815 and shared libraries to facilitate symbol resolution. They may not |
| 816 be reused as linker inputs in subsequent link steps. |
| 817 |
| 818 Accordingly, GYP performs an operation referred to as “static library |
| 819 dependency adjustment,” in which it makes each linker output target |
| 820 (shared libraries and executables) link against the static libraries it |
| 821 depends on, either directly or indirectly. Because the linkable targets |
| 822 link against these static libraries, they are also made direct |
| 823 dependents of the static libraries. |
| 824 |
| 825 As part of this process, GYP is also able to remove the direct |
| 826 dependency relationships between two static library targets, as a |
| 827 dependent static library does not actually need to link against a |
| 828 dependency static library. This removal facilitates speedier builds |
| 829 under some build systems, as they are now free to build the two targets |
| 830 in parallel. The removal of this dependency is incorrect in some cases, |
| 831 such as when the dependency target contains [rules](#rules) or |
| 832 [actions](#actions) that generate header files required by the |
| 833 dependent target. In such cases, the dependency target, the one |
| 834 providing the side-effect files, must declare itself as a |
| 835 [hard\_dependency](#hard_dependency). This setting instructs GYP to |
| 836 not remove the dependency link between two static library targets in its |
| 837 generated output. |
| 838 |
| 839 ## Loading Files to Resolve Dependencies |
| 840 |
| 841 When GYP runs, it loads all `.gyp` files needed to resolve dependencies |
| 842 found in [dependencies](#dependencies) sections. These files are not |
| 843 merged into the files that reference them, but they may contain special |
| 844 sections that are merged into dependent target dictionaries. |
| 845 |
| 846 ## Build Configurations |
| 847 |
| 848 Explain this. |
| 849 |
| 850 ## List Filters |
| 851 |
| 852 GYP allows list items to be filtered by “exclusions” and “patterns.” |
| 853 Any list containing string values in a dictionary may have this |
| 854 filtering applied. For the purposes of this section, a list modified by |
| 855 exclusions or patterns is referred to as a “base list”, in contrast to |
| 856 the “exclusion list” and “pattern list” that operates on it. |
| 857 |
| 858 * For a base list identified by key name `key`, the `key!` list |
| 859 provides exclusions. |
| 860 * For a base list identified by key name `key`, the `key/` list |
| 861 provides regular expression pattern-based filtering. |
| 862 |
| 863 Both `key!` and `key/` may be present. The `key!` exclusion list will |
| 864 be processed first, followed by the `key/` pattern list. |
| 865 |
| 866 Exclusion lists are most powerful when used in conjunction with |
| 867 [conditionals](#Conditionals). |
| 868 |
| 869 ## Exclusion Lists (!) |
| 870 |
| 871 An exclusion list provides a way to remove items from the related list |
| 872 based on exact matching. Any item found in an exclusion list will be |
| 873 removed from the corresponding base list. |
| 874 |
| 875 #### Example |
| 876 |
| 877 This example excludes files from the `sources` based on the setting of |
| 878 the `OS` variable. |
| 879 |
| 880 ``` |
| 881 { |
| 882 'sources:' [ |
| 883 'mac_util.mm', |
| 884 'win_util.cc', |
| 885 ], |
| 886 'conditions': [ |
| 887 ['OS=="mac"', {'sources!': ['win_util.cc']}], |
| 888 ['OS=="win"', {'sources!': ['mac_util.cc']}], |
| 889 ], |
| 890 } |
| 891 ``` |
| 892 |
| 893 ## Pattern Lists (/) |
| 894 |
| 895 Pattern lists are similar to, but more powerful than, [exclusion |
| 896 lists](#Exclusion_Lists_(!)). Each item in a pattern list is itself |
| 897 a two-element list. The first item is a string, either `'include'` or |
| 898 `'exclude'`, specifying the action to take. The second item is a string |
| 899 specifying a regular expression. Any item in the base list matching the |
| 900 regular expression pattern will either be included or excluded, based on |
| 901 the action specified. |
| 902 |
| 903 Items in a pattern list are processed in sequence, and an excluded item |
| 904 that is later included will not be removed from the list (unless it is |
| 905 subsequently excluded again.) |
| 906 |
| 907 Pattern lists are processed after [exclusion |
| 908 lists](#Exclusion_Lists_(!)), so it is possible for a pattern list to |
| 909 re-include items previously excluded by an exclusion list. |
| 910 |
| 911 Nothing is actually removed from a base list until all items in an |
| 912 [exclusion list](#Exclusion_Lists_(!)) and pattern list have been |
| 913 evaluated. This allows items to retain their correct position relative |
| 914 to one another even after being excluded and subsequently included. |
| 915 |
| 916 #### Example |
| 917 |
| 918 In this example, a uniform naming scheme is adopted for |
| 919 platform-specific files. |
| 920 |
| 921 ``` |
| 922 { |
| 923 'sources': [ |
| 924 'io_posix.cc', |
| 925 'io_win.cc', |
| 926 'launcher_mac.cc', |
| 927 'main.cc', |
| 928 'platform_util_linux.cc', |
| 929 'platform_util_mac.mm', |
| 930 ], |
| 931 'sources/': [ |
| 932 [['exclude', '_win\\.cc$']], |
| 933 ], |
| 934 'conditions': [ |
| 935 ['OS!="linux"', {'sources/': [['exclude', '_linux\\.cc$']]}], |
| 936 ['OS!="mac"', {'sources/': [['exclude', '_mac\\.cc|mm?$']]}], |
| 937 ['OS=="win"', {'sources/': [ |
| 938 [['include', '_win\\.cc$']], |
| 939 [['exclude', '_posix\\.cc$']], |
| 940 ]}], |
| 941 ], |
| 942 } |
| 943 ``` |
| 944 |
| 945 After the pattern list is applied, `sources` will have the following |
| 946 values, depending on the setting of `OS`: |
| 947 |
| 948 * When `OS` is `linux`: `['io_posix.cc', 'main.cc', |
| 949 'platform_util_linux.cc']` |
| 950 * When `OS` is `mac`: `['io_posix.cc', 'launcher_mac.cc', 'main.cc', |
| 951 'platform_util_mac.mm']` |
| 952 * When `OS` is `win`: `['io_win.cc', 'main.cc', |
| 953 'platform_util_win.cc']` |
| 954 |
| 955 Note that when `OS` is `win`, the `include` for `_win.cc` files is |
| 956 processed after the `exclude` matching the same pattern, because the |
| 957 `sources/` list participates in [merging](#Merging) during |
| 958 [conditional evaluation](#Conditonals) just like any other list |
| 959 would. This guarantees that the `_win.cc` files, previously |
| 960 unconditionally excluded, will be re-included when `OS` is `win`. |
| 961 |
| 962 ## Locating Excluded Items |
| 963 |
| 964 In some cases, a GYP generator needs to access to items that were |
| 965 excluded by an [exclusion list](#Exclusion_Lists_(!)) or [pattern |
| 966 list](#Pattern_Lists_(/)). When GYP excludes items during processing |
| 967 of either of these list types, it places the results in an `_excluded` |
| 968 list. In the example above, when `OS` is `mac`, `sources_excluded` |
| 969 would be set to `['io_win.cc', 'platform_util_linux.cc']`. Some GYP |
| 970 generators use this feature to display excluded files in the project |
| 971 files they generate for the convenience of users, who may wish to refer |
| 972 to other implementations. |
| 973 |
| 974 ## Processing Order |
| 975 |
| 976 GYP uses a defined and predictable order to execute the various steps |
| 977 performed between loading files and generating output. |
| 978 |
| 979 * Load files. |
| 980 * Load `.gyp` files. Merge any [command-line |
| 981 includes](#Including_Other_Files) into each `.gyp` file’s root |
| 982 dictionary. As [includes](#Including_Other_Files) are found, |
| 983 load them as well and [merge](#Merging) them into the scope in |
| 984 which the [includes](#includes) section was found. |
| 985 * Perform [“early” or “pre”](#Early_and_Late_Phases) [variable |
| 986 expansion and conditional |
| 987 evaluation](#Variables_and_Conditionals). |
| 988 * [Merge](#Merging) each [target’s](#targets) dictionary into |
| 989 the `.gyp` file’s root [target\_defaults](#target_defaults) |
| 990 dictionary. |
| 991 * Scan each [target](#targets) for |
| 992 [dependencies](#dependencies), and repeat the above steps for |
| 993 any newly-referenced `.gyp` files not yet loaded. |
| 994 * Scan each [target](#targets) for wildcard |
| 995 [dependencies](#dependencies), expanding the wildcards. |
| 996 * Process [dependent settings](#Dependent_Settings). These |
| 997 sections are processed, in order: |
| 998 * [all\_dependent\_settings](#all_dependent_settings) |
| 999 * [direct\_dependent\_settings](#direct_dependent_settings) |
| 1000 * [link\_dependent\_settings](#link_dependent_settings) |
| 1001 * Perform [static library dependency |
| 1002 adjustment](#Linking_Dependencies). |
| 1003 * Perform [“late,” “post,” or “target”](#Early_and_Late_Phases) |
| 1004 [variable expansion and conditional |
| 1005 evaluation](#Variables_and_Conditionals) on [target](#targets) |
| 1006 dictionaries. |
| 1007 * Merge [target](#targets) settings into |
| 1008 [configurations](#configurations) as appropriate. |
| 1009 * Process [exclusion and pattern |
| 1010 lists](#List_Exclusions_and_Patterns). |
| 1011 |
| 1012 ## Settings Keys |
| 1013 |
| 1014 ### Settings that may appear anywhere |
| 1015 |
| 1016 #### conditions |
| 1017 |
| 1018 _List of `condition` items_ |
| 1019 |
| 1020 A `conditions` section introduces a subdictionary that is only merged |
| 1021 into the enclosing scope based on the evaluation of a conditional |
| 1022 expression. Each `condition` within a `conditions` list is itself a |
| 1023 list of at least two items: |
| 1024 |
| 1025 1. A string containing the conditional expression itself. Conditional |
| 1026 expressions may take the following forms: |
| 1027 * For string values, `var=="value"` and `var!="value"` to test |
| 1028 equality and inequality. For example, `'OS=="linux"'` is true |
| 1029 when the `OS` variable is set to `"linux"`. |
| 1030 * For integer values, `var==value`, `var!=value`, `var<value`, |
| 1031 `var<=value`, `var>=value`, and `var>value`, to test equality and |
| 1032 several common forms of inequality. For example, |
| 1033 `'chromium_code==0'` is true when the `chromium_code` variable is |
| 1034 set to `0`. |
| 1035 * It is an error for a conditional expression to reference any |
| 1036 undefined variable. |
| 1037 1. A dictionary containing the subdictionary to be merged into the |
| 1038 enclosing scope if the conditional expression evaluates to true. |
| 1039 |
| 1040 These two items can be followed by any number of similar two items that |
| 1041 will be evaluated if the previous conditional expression does not |
| 1042 evaluate to true. |
| 1043 |
| 1044 An additional optional dictionary can be appended to this sequence of |
| 1045 two items. This optional dictionary will be merged into the enclosing |
| 1046 scope if none of the conditional expressions evaluate to true. |
| 1047 |
| 1048 Within a `conditions` section, each item is processed sequentially, so |
| 1049 it is possible to predict the order in which operations will occur. |
| 1050 |
| 1051 There is no restriction on nesting `conditions` sections. |
| 1052 |
| 1053 `conditions` sections are very similar to `target_conditions` sections. |
| 1054 See target\_conditions. |
| 1055 |
| 1056 #### Example |
| 1057 |
| 1058 ``` |
| 1059 { |
| 1060 'sources': [ |
| 1061 'common.cc', |
| 1062 ], |
| 1063 'conditions': [ |
| 1064 ['OS=="mac"', {'sources': ['mac_util.mm']}], |
| 1065 ['OS=="win"', {'sources': ['win_main.cc']}, {'sources': ['posix_main.cc']}], |
| 1066 ['OS=="mac"', {'sources': ['mac_impl.mm']}, |
| 1067 'OS=="win"', {'sources': ['win_impl.cc']}, |
| 1068 {'sources': ['default_impl.cc']} |
| 1069 ], |
| 1070 ], |
| 1071 } |
| 1072 ``` |
| 1073 |
| 1074 Given this input, the `sources` list will take on different values based |
| 1075 on the `OS` variable. |
| 1076 |
| 1077 * If `OS` is `"mac"`, `sources` will contain `['common.cc', |
| 1078 'mac_util.mm', 'posix_main.cc', 'mac_impl.mm']`. |
| 1079 * If `OS` is `"win"`, `sources` will contain `['common.cc', |
| 1080 'win_main.cc', 'win_impl.cc']`. |
| 1081 * If `OS` is any other value such as `"linux"`, `sources` will contain |
| 1082 `['common.cc', 'posix_main.cc', 'default_impl.cc']`. |
OLD | NEW |