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 |