diff options
Diffstat (limited to 'node_modules/node-gyp/gyp/docs/InputFormatReference.md')
| -rw-r--r-- | node_modules/node-gyp/gyp/docs/InputFormatReference.md | 1083 |
1 files changed, 0 insertions, 1083 deletions
diff --git a/node_modules/node-gyp/gyp/docs/InputFormatReference.md b/node_modules/node-gyp/gyp/docs/InputFormatReference.md deleted file mode 100644 index 4b114f2..0000000 --- a/node_modules/node-gyp/gyp/docs/InputFormatReference.md +++ /dev/null @@ -1,1083 +0,0 @@ -# Input Format Reference - -## Primitive Types - -The following primitive types are found within input files: - - * String values, which may be represented by enclosing them in - `'single quotes'` or `"double quotes"`. By convention, single - quotes are used. - * Integer values, which are represented in decimal without any special - decoration. Integers are fairly rare in input files, but have a few - applications in boolean contexts, where the convention is to - represent true values with `1` and false with `0`. - * Lists, which are represented as a sequence of items separated by - commas (`,`) within square brackets (`[` and `]`). A list may - contain any other primitive types, including other lists. - Generally, each item of a list must be of the same type as all other - items in the list, but in some cases (such as within `conditions` - sections), the list structure is more tightly specified. A trailing - comma is permitted. - - This example list contains three string values. - - ``` - [ 'Generate', 'Your', 'Projects', ] - ``` - - * Dictionaries, which map keys to values. All keys are strings. - Values may be of any other primitive type, including other - dictionaries. A dictionary is enclosed within curly braces (`{` and - `}`). Keys precede values, separated by a colon (`:`). Successive - dictionary entries are separated by commas (`,`). A trailing comma - is permitted. It is an error for keys to be duplicated within a - single dictionary as written in an input file, although keys may - replace other keys during [merging](#Merging). - - This example dictionary maps each of three keys to different values. - - ``` - { - 'inputs': ['version.c.in'], - 'outputs': ['version.c'], - 'process_outputs_as_sources': 1, - } - ``` - -## Overall Structure - -A GYP input file is organized as structured data. At the root scope of -each `.gyp` or `.gypi` (include) file is a dictionary. The keys and -values of this dictionary, along with any descendants contained within -the values, provide the data contained within the file. This data is -given meaning by interpreting specific key names and their associated -values in specific ways (see [Settings Keys](#Settings_Keys)). - -### Comments (#) - -Within an input file, a comment is introduced by a pound sign (`#`) not -within a string. Any text following the pound sign, up until the end of -the line, is treated as a comment. - -#### Example - -``` -{ - 'school_supplies': [ - 'Marble composition book', - 'Sharp #2 pencil', - 'Safety scissors', # You still shouldn't run with these - ], -} -``` - -In this example, the # in `'Sharp #2 pencil'` is not taken as -introducing a comment because it occurs within a string, but the text -after `'Safety scissors'` is treated as a comment having no impact on -the data within the file. - -## Merging - -### Merge Basics (=, ?, +) - -Many operations on GYP input files occurs by merging dictionary and list -items together. During merge operations, it is important to recognize -the distinction between source and destination values. Items from the -source value are merged into the destination, which leaves the source -unchanged and the destination modified by the source. A dictionary may -only be merged into another dictionary, and a list may only be merged -into another list. - - * When merging a dictionary, for each key in the source: - * If the key does not exist in the destination dictionary, insert it - and copy the associated value directly. - * If the key does exist: - * If the associated value is a dictionary, perform the dictionary - merging procedure using the source's and destination's value - dictionaries. - * If the associated value is a list, perform the list merging - procedure using the source's and destination's value lists. - * If the associated value is a string or integer, the destination - value is replaced by the source value. - * When merging a list, merge according to the suffix appended to the - key name, if the list is a value within a dictionary. - * If the key ends with an equals sign (`=`), the policy is for the - source list to completely replace the destination list if it - exists. _Mnemonic: `=` for assignment._ - * If the key ends with a question mark (`?`), the policy is for the - source list to be set as the destination list only if the key is - not already present in the destination. _Mnemonic: `?` for - conditional assignment_. - * If the key ends with a plus sign (`+`), the policy is for the - source list contents to be prepended to the destination list. - _Mnemonic: `+` for addition or concatenation._ - * If the list key is undecorated, the policy is for the source list - contents to be appended to the destination list. This is the - default list merge policy. - -#### Example - -Source dictionary: - -``` -{ - 'include_dirs+': [ - 'shared_stuff/public', - ], - 'link_settings': { - 'libraries': [ - '-lshared_stuff', - ], - }, - 'test': 1, -} -``` - -Destination dictionary: - -``` -{ - 'target_name': 'hello', - 'sources': [ - 'kitty.cc', - ], - 'include_dirs': [ - 'headers', - ], - 'link_settings': { - 'libraries': [ - '-lm', - ], - 'library_dirs': [ - '/usr/lib', - ], - }, - 'test': 0, -} -``` - -Merged dictionary: - -``` -{ - 'target_name': 'hello', - 'sources': [ - 'kitty.cc', - ], - 'include_dirs': [ - 'shared_stuff/public', # Merged, list item prepended due to include_dirs+ - 'headers', - ], - 'link_settings': { - 'libraries': [ - '-lm', - '-lshared_stuff', # Merged, list item appended - ], - 'library_dirs': [ - '/usr/lib', - ], - }, - 'test': 1, # Merged, int value replaced -} -``` - -## Pathname Relativization - -In a `.gyp` or `.gypi` file, many string values are treated as pathnames -relative to the file in which they are defined. - -String values associated with the following keys, or contained within -lists associated with the following keys, are treated as pathnames: - - * destination - * files - * include\_dirs - * inputs - * libraries - * library\_dirs - * outputs - * sources - * mac\_bundle\_resources - * mac\_framework\_dirs - * msvs\_cygwin\_dirs - * msvs\_props - -Additionally, string values associated with keys ending in the following -suffixes, or contained within lists associated with keys ending in the -following suffixes, are treated as pathnames: - - * `_dir` - * `_dirs` - * `_file` - * `_files` - * `_path` - * `_paths` - -However, any string value beginning with any of these characters is -excluded from pathname relativization: - - * `/` for identifying absolute paths. - * `$` for introducing build system variable expansions. - * `-` to support specifying such items as `-llib`, meaning “library - `lib` in the library search path.” - * `<`, `>`, and `!` for GYP expansions. - -When merging such relative pathnames, they are adjusted so that they can -remain valid relative pathnames, despite being relative to a new home. - -#### Example - -Source dictionary from `../build/common.gypi`: - -``` -{ - 'include_dirs': ['include'], # Treated as relative to ../build - 'library_dirs': ['lib'], # Treated as relative to ../build - 'libraries': ['-lz'], # Not treated as a pathname, begins with a dash - 'defines': ['NDEBUG'], # defines does not contain pathnames -} -``` - -Target dictionary, from `base.gyp`: - -``` -{ - 'sources': ['string_util.cc'], -} -``` - -Merged dictionary: - -``` -{ - 'sources': ['string_util.cc'], - 'include_dirs': ['../build/include'], - 'library_dirs': ['../build/lib'], - 'libraries': ['-lz'], - 'defines': ['NDEBUG'], -} -``` - -Because of pathname relativization, after the merge is complete, all of -the pathnames in the merged dictionary are valid relative to the -directory containing `base.gyp`. - -## List Singletons - -Some list items are treated as singletons, and the list merge process -will enforce special rules when merging them. At present, any string -item in a list that does not begin with a dash (`-`) is treated as a -singleton, although **this is subject to change.** When appending or -prepending a singleton to a list, if the item is already in the list, -only the earlier instance is retained in the merged list. - -#### Example - -Source dictionary: - -``` -{ - 'defines': [ - 'EXPERIMENT=1', - 'NDEBUG', - ], -} -``` - -Destination dictionary: - -``` -{ - 'defines': [ - 'NDEBUG', - 'USE_THREADS', - ], -} -``` - -Merged dictionary: - -``` -{ - 'defines': [ - 'NDEBUG', - 'USE_THREADS', - 'EXPERIMENT=1', # Note that NDEBUG is not appended after this. - ], -} -``` - -## Including Other Files - -If the `-I` (`--include`) argument was used to invoke GYP, any files -specified will be implicitly merged into the root dictionary of all -`.gyp` files. - -An [includes](#includes) section may be placed anywhere within a -`.gyp` or `.gypi` (include) file. `includes` sections contain lists of -other files to include. They are processed sequentially and merged into -the enclosing dictionary at the point that the `includes` section was -found. `includes` sections at the root of a `.gyp` file dictionary are -merged after any `-I` includes from the command line. - -[includes](#includes) sections are processed immediately after a file is -loaded, even before [variable and conditional -processing](#Variables_and_Conditionals), so it is not possible to -include a file based on a [variable reference](#Variable_Expansions). -While it would be useful to be able to include files based on variable -expansions, it is most likely more useful to allow included files access -to variables set by the files that included them. - -An [includes](#includes) section may, however, be placed within a -[conditional](#Conditionals) section. The included file itself will -be loaded unconditionally, but its dictionary will be discarded if the -associated condition is not true. - -## Variables and Conditionals - -### Variables - -There are three main types of variables within GYP. - - * Predefined variables. By convention, these are named with - `CAPITAL_LETTERS`. Predefined variables are set automatically by - GYP. They may be overridden, but it is not advisable to do so. See - [Predefined Variables](#Predefined_Variables) for a list of - variables that GYP provides. - * User-defined variables. Within any dictionary, a key named - `variables` can be provided, containing a mapping between variable - names (keys) and their contents (values), which may be strings, - integers, or lists of strings. By convention, user-defined - variables are named with `lowercase_letters`. - * Automatic variables. Within any dictionary, any key with a string - value has a corresponding automatic variable whose name is the same - as the key name with an underscore (`_`) prefixed. For example, if - your dictionary contains `type: 'static_library'`, an automatic - variable named `_type` will be provided, and its value will be a - string, `'static_library'`. - -Variables are inherited from enclosing scopes. - -### Providing Default Values for Variables (%) - -Within a `variables` section, keys named with percent sign (`%`) -suffixes mean that the variable should be set only if it is undefined at -the time it is processed. This can be used to provide defaults for -variables that would otherwise be undefined, so that they may reliably -be used in [variable expansion or conditional -processing](#Variables_and_Conditionals). - -### Predefined Variables - -Each GYP generator module provides defaults for the following variables: - - * `OS`: The name of the operating system that the generator produces - output for. Common values for values for `OS` are: - - * `'linux'` - * `'mac'` - * `'win'` - - But other values may be encountered and this list should not be - considered exhaustive. The `gypd` (debug) generator module does not - provide a predefined value for `OS`. When invoking GYP with the - `gypd` module, if a value for `OS` is needed, it must be provided on - the command line, such as `gyp -f gypd -DOS=mac`. - - GYP generators also provide defaults for these variables. They may - be expressed in terms of variables used by the build system that - they generate for, often in `$(VARIABLE)` format. For example, the - GYP `PRODUCT_DIR` variable maps to the Xcode `BUILT_PRODUCTS_DIR` - variable, so `PRODUCT_DIR` is defined by the Xcode generator as - `$(BUILT_PRODUCTS_DIR)`. - * `EXECUTABLE_PREFIX`: A prefix, if any, applied to executable names. - Usually this will be an empty string. - * `EXECUTABLE_SUFFIX`: A suffix, if any, applied to executable names. - On Windows, this will be `.exe`, elsewhere, it will usually be an - empty string. - * `INTERMEDIATE_DIR`: A directory that can be used to place - intermediate build results in. `INTERMEDIATE_DIR` is only - guaranteed to be accessible within a single target (See targets). - This variable is most useful within the context of rules and actions - (See rules, See actions). Compare with `SHARED_INTERMEDIATE_DIR`. - * `PRODUCT_DIR`: The directory in which the primary output of each - target, such as executables and libraries, is placed. - * `RULE_INPUT_ROOT`: The base name for the input file (e.g. "`foo`"). - See Rules. - * `RULE_INPUT_EXT`: The file extension for the input file (e.g. - "`.cc`"). See Rules. - * `RULE_INPUT_NAME`: Full name of the input file (e.g. "`foo.cc`"). - See Rules. - * `RULE_INPUT_PATH`: Full path to the input file (e.g. - "`/bar/foo.cc`"). See Rules. - * `SHARED_INTERMEDIATE_DIR`: A directory that can be used to place - intermediate build results in, and have them be accessible to other - targets. Unlike `INTERMEDIATE_DIR`, each target in a project, - possibly spanning multiple `.gyp` files, shares the same - `SHARED_INTERMEDIATE_DIR`. - -The following additional predefined variables may be available under -certain circumstances: - - * `DEPTH`. When GYP is invoked with a `--depth` argument, when - processing any `.gyp` file, `DEPTH` will be a relative path from the - `.gyp` file to the directory specified by the `--depth` argument. - -### User-Defined Variables - -A user-defined variable may be defined in terms of other variables, but -not other variables that have definitions provided in the same scope. - -### Variable Expansions (<, >, <@, >@) - -GYP provides two forms of variable expansions, “early” or “pre” -expansions, and “late,” “post,” or “target” expansions. They have -similar syntax, differing only in the character used to introduce them. - - * Early expansions are introduced by a less-than (`<`) character. - _Mnemonic: the arrow points to the left, earlier on a timeline._ - * Late expansions are introduced by a less-than (`>`) character. - _Mnemonic: the arrow points to the right, later on a timeline._ - -The difference the two phases of expansion is described in [Early and -Late Phases](#Early_and_Late_Phases). - -These characters were chosen based upon the requirement that they not -conflict with the variable format used natively by build systems. While -the dollar sign (`$`) is the most natural fit for variable expansions, -its use was ruled out because most build systems already use that -character for their own variable expansions. Using different characters -means that no escaping mechanism was needed to differentiate between GYP -variables and build system variables, and writing build system variables -into GYP files is not cumbersome. - -Variables may contain lists or strings, and variable expansions may -occur in list or string context. There are variant forms of variable -expansions that may be used to determine how each type of variable is to -be expanded in each context. - - * When a variable is referenced by `<(VAR)` or `>(VAR)`: - * If `VAR` is a string, the variable reference within the string is - replaced by variable's string value. - * If `VAR` is a list, the variable reference within the string is - replaced by a string containing the concatenation of all of the - variable’s list items. Generally, the items are joined with - spaces between each, but the specific behavior is - generator-specific. The precise encoding used by any generator - should be one that would allow each list item to be treated as a - separate argument when used as program arguments on the system - that the generator produces output for. - * When a variable is referenced by `<@(VAR)` or `>@(VAR)`: - * The expansion must occur in list context. - * The list item must be `'<@(VAR)'` or `'>@(VAR)'` exactly. - * If `VAR` is a list, each of its elements are inserted into the - list in which expansion is taking place, replacing the list item - containing the variable reference. - * If `VAR` is a string, the string is converted to a list which is - inserted into the list in which expansion is taking place as - above. The conversion into a list is generator-specific, but - generally, spaces in the string are taken as separators between - list items. The specific method of converting the string to a - list should be the inverse of the encoding method used to expand - list variables in string context, above. - -GYP treats references to undefined variables as errors. - -### Command Expansions (<!, <!@) - -Command expansions function similarly to variable expansions, but -instead of resolving variable references, they cause GYP to execute a -command at generation time and use the command’s output as the -replacement. Command expansions are introduced by a less than and -exclamation mark (`<!`). - -In a command expansion, the entire string contained within the -parentheses is passed to the system’s shell. The command’s output is -assigned to a string value that may subsequently be expanded in list -context in the same way as variable expansions if an `@` character is -used. - -In addition, command expansions (unlike other variable expansions) may -include nested variable expansions. So something like this is allowed: - -``` -'variables' : [ - 'foo': '<!(echo Build Date <!(date))', -], -``` - -expands to: - -``` -'variables' : [ - 'foo': 'Build Date 02:10:38 PM Fri Jul 24, 2009 -0700 PDT', -], -``` - -You may also put commands into arrays in order to quote arguments (but -note that you need to use a different string quoting character): - -``` -'variables' : [ - 'files': '<!(["ls", "-1", "Filename With Spaces"])', -], -``` - -GYP treats command failures (as indicated by a nonzero exit status) -during command expansion as errors. - -#### Example - -``` -{ - 'sources': [ - '!(echo filename with space.cc)', - ], - 'libraries': [ - '!@(pkg-config --libs-only-l apr-1)', - ], -} -``` - -might expand to: - -``` -{ - 'sources': [ - 'filename with space.cc', # no @, expands into a single string - ], - 'libraries': [ # @ was used, so there's a separate list item for each lib - '-lapr-1', - '-lpthread', - ], -} -``` - -## Conditionals - -Conditionals use the same set of variables used for variable expansion. -As with variable expansion, there are two phases of conditional -evaluation: - - * “Early” or “pre” conditional evaluation, introduced in - [conditions](#conditions) sections. - * “Late,” “post,” or “target” conditional evaluation, introduced in - [target\_conditions](#target_conditions) sections. - -The syntax for each type is identical, they differ only in the key name -used to identify them and the timing of their evaluation. A more -complete description of syntax and use is provided in -[conditions](#conditions). - -The difference the two phases of evaluation is described in [Early and -Late Phases](#Early_and_Late_Phases). - -## Timing of Variable Expansion and Conditional Evaluation - -### Early and Late Phases - -GYP performs two phases of variable expansion and conditional evaluation: - - * The “early” or “pre” phase operates on [conditions](#conditions) - sections and the `<` form of [variable - expansions](#Variable_Expansions). - * The “late,” “post,” or “target” phase operates on - [target\_conditions](#target_conditions) sections, the `>` form - of [variable expansions](#Variable_Expansions), - and on the `!` form of [command - expansions](#Command_Expansions_(!,_!@)). - -These two phases are provided because there are some circumstances in -which each is desirable. - -The “early” phase is appropriate for most expansions and evaluations. -“Early” expansions and evaluations may be performed anywhere within any -`.gyp` or `.gypi` file. - -The “late” phase is appropriate when expansion or evaluation must be -deferred until a specific section has been merged into target context. -“Late” expansions and evaluations only occur within `targets` sections -and their descendants. The typical use case for a late-phase expansion -is to provide, in some globally-included `.gypi` file, distinct -behaviors depending on the specifics of a target. - -#### Example - -Given this input: - -``` -{ - 'target_defaults': { - 'target_conditions': [ - ['_type=="shared_library"', {'cflags': ['-fPIC']}], - ], - }, - 'targets': [ - { - 'target_name': 'sharing_is_caring', - 'type': 'shared_library', - }, - { - 'target_name': 'static_in_the_attic', - 'type': 'static_library', - }, - ] -} -``` - -The conditional needs to be evaluated only in target context; it is -nonsense outside of target context because no `_type` variable is -defined. [target\_conditions](#target_conditions) allows evaluation -to be deferred until after the [targets](#targets) sections are -merged into their copies of [target\_defaults](#target_defaults). -The resulting targets, after “late” phase processing: - -``` -{ - 'targets': [ - { - 'target_name': 'sharing_is_caring', - 'type': 'shared_library', - 'cflags': ['-fPIC'], - }, - { - 'target_name': 'static_in_the_attic', - 'type': 'static_library', - }, - ] -} -``` - -### Expansion and Evaluation Performed Simultaneously - -During any expansion and evaluation phase, both expansion and evaluation -are performed simultaneously. The process for handling variable -expansions and conditional evaluation within a dictionary is: - - * Load [automatic variables](#Variables) (those with leading - underscores). - * If a [variables](#variables) section is present, recurse into its - dictionary. This allows [conditionals](#Conditionals) to be - present within the `variables` dictionary. - * Load [Variables user-defined variables](#User-Defined) from the - [variables](#variables) section. - * For each string value in the dictionary, perform [variable - expansion](#Variable_Expansions) and, if operating - during the “late” phase, [command - expansions](#Command_Expansions). - * Reload [automatic variables](#Variables) and [Variables - user-defined variables](#User-Defined) because the variable - expansion step may have resulted in changes to the automatic - variables. - * If a [conditions](#conditions) or - [target\_conditions](#target_conditions) section (depending on - phase) is present, recurse into its dictionary. This is done after - variable expansion so that conditionals may take advantage of - expanded automatic variables. - * Evaluate [conditionals](#Conditionals). - * Reload [automatic variables](#Variables) and [Variables - user-defined variables](#User-Defined) because the conditional - evaluation step may have resulted in changes to the automatic - variables. - * Recurse into child dictionaries or lists that have not yet been - processed. - -One quirk of this ordering is that you cannot expect a -[variables](#variables) section within a dictionary’s -[conditional](#Conditionals) to be effective in the dictionary -itself, but the added variables will be effective in any child -dictionaries or lists. It is thought to be far more worthwhile to -provide resolved [automatic variables](#Variables) to -[conditional](#Conditionals) sections, though. As a workaround, to -conditionalize variable values, place a [conditions](#conditions) or -[target\_conditions](#target_conditions) section within the -[variables](#variables) section. - -## Dependencies and Dependents - -In GYP, “dependents” are targets that rely on other targets, called -“dependencies.” Dependents declare their reliance with a special -section within their target dictionary, -[dependencies](#dependencies). - -### Dependent Settings - -It is useful for targets to “advertise” settings to their dependents. -For example, a target might require that all of its dependents add -certain directories to their include paths, link against special -libraries, or define certain preprocessor macros. GYP allows these -cases to be handled gracefully with “dependent settings” sections. -There are three types of such sections: - - * [direct\_dependent\_settings](#direct_dependent_settings), which - advertises settings to a target's direct dependents only. - * [all\_dependent\_settings](#all_dependnet_settings), which - advertises settings to all of a target's dependents, both direct and - indirect. - * [link\_settings](#link_settings), which contains settings that - should be applied when a target’s object files are used as linker - input. - -Furthermore, in some cases, a target needs to pass its dependencies’ -settings on to its own dependents. This might happen when a target’s -own public header files include header files provided by its dependency. -[export\_dependent\_settings](#export_dependent_settings) allows a -target to declare dependencies for which -[direct\_dependent\_settings](#direct_dependent_settings) should be -passed through to its own dependents. - -Dependent settings processing merges a copy of the relevant dependent -settings dictionary from a dependency into its relevant dependent -targets. - -In most instances, -[direct\_dependent\_settings](#direct_dependent_settings) will be -used. There are very few cases where -[all\_dependent\_settings](#all_dependent_settings) is actually -correct; in most of the cases where it is tempting to use, it would be -preferable to declare -[export\_dependent\_settings](#export_dependent_settings). Most -[libraries](#libraries) and [library\_dirs](#library_dirs) -sections should be placed within [link\_settings](#link_settings) -sections. - -#### Example - -Given: - -``` -{ - 'targets': [ - { - 'target_name': 'cruncher', - 'type': 'static_library', - 'sources': ['cruncher.cc'], - 'direct_dependent_settings': { - 'include_dirs': ['.'], # dependents need to find cruncher.h. - }, - 'link_settings': { - 'libraries': ['-lm'], # cruncher.cc does math. - }, - }, - { - 'target_name': 'cruncher_test', - 'type': 'executable', - 'dependencies': ['cruncher'], - 'sources': ['cruncher_test.cc'], - }, - ], -} -``` - -After dependent settings processing, the dictionary for `cruncher_test` -will be: - -``` -{ - 'target_name': 'cruncher_test', - 'type': 'executable', - 'dependencies': ['cruncher'], # implies linking against cruncher - 'sources': ['cruncher_test.cc'], - 'include_dirs': ['.'] - 'libraries': ['-lm'], -}, -``` - -If `cruncher` was declared as a `shared_library` instead of a -`static_library`, the `cruncher_test` target would not contain `-lm`, -but instead, `cruncher` itself would link against `-lm`. - -## Linking Dependencies - -The precise meaning of a dependency relationship varies with the -[types](#type) of the [targets](#targets) at either end of the -relationship. In GYP, a dependency relationship can indicate two things -about how targets relate to each other: - - * Whether the dependent target needs to link against the dependency. - * Whether the dependency target needs to be built prior to the - dependent. If the former case is true, this case must be true as - well. - -The analysis of the first item is complicated by the differences between -static and shared libraries. - - * Static libraries are simply collections of object files (`.o` or - `.obj`) that are used as inputs to a linker (`ld` or `link.exe`). - Static libraries don't link against other libraries, they’re - collected together and used when eventually linking a shared library - or executable. - * Shared libraries are linker output and must undergo symbol - resolution. They must link against other libraries (static or - shared) in order to facilitate symbol resolution. They may be used - as libraries in subsequent link steps. - * Executables are also linker output, and also undergo symbol - resolution. Like shared libraries, they must link against static - and shared libraries to facilitate symbol resolution. They may not - be reused as linker inputs in subsequent link steps. - -Accordingly, GYP performs an operation referred to as “static library -dependency adjustment,” in which it makes each linker output target -(shared libraries and executables) link against the static libraries it -depends on, either directly or indirectly. Because the linkable targets -link against these static libraries, they are also made direct -dependents of the static libraries. - -As part of this process, GYP is also able to remove the direct -dependency relationships between two static library targets, as a -dependent static library does not actually need to link against a -dependency static library. This removal facilitates speedier builds -under some build systems, as they are now free to build the two targets -in parallel. The removal of this dependency is incorrect in some cases, -such as when the dependency target contains [rules](#rules) or -[actions](#actions) that generate header files required by the -dependent target. In such cases, the dependency target, the one -providing the side-effect files, must declare itself as a -[hard\_dependency](#hard_dependency). This setting instructs GYP to -not remove the dependency link between two static library targets in its -generated output. - -## Loading Files to Resolve Dependencies - -When GYP runs, it loads all `.gyp` files needed to resolve dependencies -found in [dependencies](#dependencies) sections. These files are not -merged into the files that reference them, but they may contain special -sections that are merged into dependent target dictionaries. - -## Build Configurations - -Explain this. - -## List Filters - -GYP allows list items to be filtered by “exclusions” and “patterns.” -Any list containing string values in a dictionary may have this -filtering applied. For the purposes of this section, a list modified by -exclusions or patterns is referred to as a “base list”, in contrast to -the “exclusion list” and “pattern list” that operates on it. - - * For a base list identified by key name `key`, the `key!` list - provides exclusions. - * For a base list identified by key name `key`, the `key/` list - provides regular expression pattern-based filtering. - -Both `key!` and `key/` may be present. The `key!` exclusion list will -be processed first, followed by the `key/` pattern list. - -Exclusion lists are most powerful when used in conjunction with -[conditionals](#Conditionals). - -## Exclusion Lists (!) - -An exclusion list provides a way to remove items from the related list -based on exact matching. Any item found in an exclusion list will be -removed from the corresponding base list. - -#### Example - -This example excludes files from the `sources` based on the setting of -the `OS` variable. - -``` -{ - 'sources:' [ - 'mac_util.mm', - 'win_util.cc', - ], - 'conditions': [ - ['OS=="mac"', {'sources!': ['win_util.cc']}], - ['OS=="win"', {'sources!': ['mac_util.cc']}], - ], -} -``` - -## Pattern Lists (/) - -Pattern lists are similar to, but more powerful than, [exclusion -lists](#Exclusion_Lists_(!)). Each item in a pattern list is itself -a two-element list. The first item is a string, either `'include'` or -`'exclude'`, specifying the action to take. The second item is a string -specifying a regular expression. Any item in the base list matching the -regular expression pattern will either be included or excluded, based on -the action specified. - -Items in a pattern list are processed in sequence, and an excluded item -that is later included will not be removed from the list (unless it is -subsequently excluded again.) - -Pattern lists are processed after [exclusion -lists](#Exclusion_Lists_(!)), so it is possible for a pattern list to -re-include items previously excluded by an exclusion list. - -Nothing is actually removed from a base list until all items in an -[exclusion list](#Exclusion_Lists_(!)) and pattern list have been -evaluated. This allows items to retain their correct position relative -to one another even after being excluded and subsequently included. - -#### Example - -In this example, a uniform naming scheme is adopted for -platform-specific files. - -``` -{ - 'sources': [ - 'io_posix.cc', - 'io_win.cc', - 'launcher_mac.cc', - 'main.cc', - 'platform_util_linux.cc', - 'platform_util_mac.mm', - ], - 'sources/': [ - ['exclude', '_win\\.cc$'], - ], - 'conditions': [ - ['OS!="linux"', {'sources/': [['exclude', '_linux\\.cc$']]}], - ['OS!="mac"', {'sources/': [['exclude', '_mac\\.cc|mm?$']]}], - ['OS=="win"', {'sources/': [ - ['include', '_win\\.cc$'], - ['exclude', '_posix\\.cc$'], - ]}], - ], -} -``` - -After the pattern list is applied, `sources` will have the following -values, depending on the setting of `OS`: - - * When `OS` is `linux`: `['io_posix.cc', 'main.cc', - 'platform_util_linux.cc']` - * When `OS` is `mac`: `['io_posix.cc', 'launcher_mac.cc', 'main.cc', - 'platform_util_mac.mm']` - * When `OS` is `win`: `['io_win.cc', 'main.cc', - 'platform_util_win.cc']` - -Note that when `OS` is `win`, the `include` for `_win.cc` files is -processed after the `exclude` matching the same pattern, because the -`sources/` list participates in [merging](#Merging) during -[conditional evaluation](#Conditonals) just like any other list -would. This guarantees that the `_win.cc` files, previously -unconditionally excluded, will be re-included when `OS` is `win`. - -## Locating Excluded Items - -In some cases, a GYP generator needs to access to items that were -excluded by an [exclusion list](#Exclusion_Lists_(!)) or [pattern -list](#Pattern_Lists_(/)). When GYP excludes items during processing -of either of these list types, it places the results in an `_excluded` -list. In the example above, when `OS` is `mac`, `sources_excluded` -would be set to `['io_win.cc', 'platform_util_linux.cc']`. Some GYP -generators use this feature to display excluded files in the project -files they generate for the convenience of users, who may wish to refer -to other implementations. - -## Processing Order - -GYP uses a defined and predictable order to execute the various steps -performed between loading files and generating output. - - * Load files. - * Load `.gyp` files. Merge any [command-line - includes](#Including_Other_Files) into each `.gyp` file’s root - dictionary. As [includes](#Including_Other_Files) are found, - load them as well and [merge](#Merging) them into the scope in - which the [includes](#includes) section was found. - * Perform [“early” or “pre”](#Early_and_Late_Phases) [variable - expansion and conditional - evaluation](#Variables_and_Conditionals). - * [Merge](#Merging) each [target’s](#targets) dictionary into - the `.gyp` file’s root [target\_defaults](#target_defaults) - dictionary. - * Scan each [target](#targets) for - [dependencies](#dependencies), and repeat the above steps for - any newly-referenced `.gyp` files not yet loaded. - * Scan each [target](#targets) for wildcard - [dependencies](#dependencies), expanding the wildcards. - * Process [dependent settings](#Dependent_Settings). These - sections are processed, in order: - * [all\_dependent\_settings](#all_dependent_settings) - * [direct\_dependent\_settings](#direct_dependent_settings) - * [link\_dependent\_settings](#link_dependent_settings) - * Perform [static library dependency - adjustment](#Linking_Dependencies). - * Perform [“late,” “post,” or “target”](#Early_and_Late_Phases) - [variable expansion and conditional - evaluation](#Variables_and_Conditionals) on [target](#targets) - dictionaries. - * Merge [target](#targets) settings into - [configurations](#configurations) as appropriate. - * Process [exclusion and pattern - lists](#List_Exclusions_and_Patterns). - -## Settings Keys - -### Settings that may appear anywhere - -#### conditions - -_List of `condition` items_ - -A `conditions` section introduces a subdictionary that is only merged -into the enclosing scope based on the evaluation of a conditional -expression. Each `condition` within a `conditions` list is itself a -list of at least two items: - - 1. A string containing the conditional expression itself. Conditional - expressions may take the following forms: - * For string values, `var=="value"` and `var!="value"` to test - equality and inequality. For example, `'OS=="linux"'` is true - when the `OS` variable is set to `"linux"`. - * For integer values, `var==value`, `var!=value`, `var<value`, - `var<=value`, `var>=value`, and `var>value`, to test equality and - several common forms of inequality. For example, - `'chromium_code==0'` is true when the `chromium_code` variable is - set to `0`. - * It is an error for a conditional expression to reference any - undefined variable. - 1. A dictionary containing the subdictionary to be merged into the - enclosing scope if the conditional expression evaluates to true. - -These two items can be followed by any number of similar two items that -will be evaluated if the previous conditional expression does not -evaluate to true. - -An additional optional dictionary can be appended to this sequence of -two items. This optional dictionary will be merged into the enclosing -scope if none of the conditional expressions evaluate to true. - -Within a `conditions` section, each item is processed sequentially, so -it is possible to predict the order in which operations will occur. - -There is no restriction on nesting `conditions` sections. - -`conditions` sections are very similar to `target_conditions` sections. -See target\_conditions. - -#### Example - -``` -{ - 'sources': [ - 'common.cc', - ], - 'conditions': [ - ['OS=="mac"', {'sources': ['mac_util.mm']}], - ['OS=="win"', {'sources': ['win_main.cc']}, {'sources': ['posix_main.cc']}], - ['OS=="mac"', {'sources': ['mac_impl.mm']}, - 'OS=="win"', {'sources': ['win_impl.cc']}, - {'sources': ['default_impl.cc']} - ], - ], -} -``` - -Given this input, the `sources` list will take on different values based -on the `OS` variable. - - * If `OS` is `"mac"`, `sources` will contain `['common.cc', - 'mac_util.mm', 'posix_main.cc', 'mac_impl.mm']`. - * If `OS` is `"win"`, `sources` will contain `['common.cc', - 'win_main.cc', 'win_impl.cc']`. - * If `OS` is any other value such as `"linux"`, `sources` will contain - `['common.cc', 'posix_main.cc', 'default_impl.cc']`. |