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