Migrate GYP docs over from the wiki.

docs/InputFormatReference.md

Index: docs/InputFormatReference.md
diff --git a/docs/InputFormatReference.md b/docs/InputFormatReference.md
new file mode 100644
index 0000000000000000000000000000000000000000..9df8650350106c813029c792b4dd35a314085fa2
--- /dev/null
+++ b/docs/InputFormatReference.md
@@ -0,0 +1,1082 @@
+# 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']`.