Promote documents in md-pages branch.

docs/InputFormatReference.md

-# 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']`.