Index: docs/InputFormatReference.md |
diff --git a/docs/InputFormatReference.md b/docs/InputFormatReference.md |
deleted file mode 100644 |
index c2556e6e81712f0c429d678ca1571872583fcf39..0000000000000000000000000000000000000000 |
--- a/docs/InputFormatReference.md |
+++ /dev/null |
@@ -1,1082 +0,0 @@ |
-# Input Format Reference |
- |
-[TOC] |
- |
-## 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 |
- * 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 |
- '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'], |
- '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']`. |