Forward bundle product_type to the compile_xcassets tool.

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## **\--args**: Specifies build arguments overrides.
 
 ```
   See "gn help buildargs" for an overview of how build arguments work.
 
   Most operations take a build directory. The build arguments are taken
@@ skipping 606 matching lines @@
   gn desc out/Foo :base_unittests deps --tree
       Shows a dependency tree of the "base_unittests" project in
       the current directory.
 
   gn desc out/Debug //base defines --blame
       Shows defines set for the //base:base target, annotated by where
       each one was set from.
 
 
 ```
-## **gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn**
+## **gn format [\--dump-tree] (\--stdin | <build_file>)**
 
 ```
   Formats .gn file to a standard format.
 
   The contents of some lists ('sources', 'deps', etc.) will be sorted to
   a canonical order. To suppress this, you can add a comment of the form
   "# NOSORT" immediately preceeding the assignment. e.g.
 
   # NOSORT
   sources = [
     "z.cc",
     "a.cc",
   ]
 
 ```
 
 ### **Arguments**
+
 ```
   --dry-run
       Does not change or output anything, but sets the process exit code
       based on whether output would be different than what's on disk.
       This is useful for presubmit/lint-type checks.
       - Exit code 0: successful format, matches on disk.
       - Exit code 1: general failure (parse error, etc.)
       - Exit code 2: successful format, but differs from on disk.
 
   --dump-tree
-      For debugging only, dumps the parse tree.
-
-  --in-place
-      Instead of writing the formatted file to stdout, replace the input
-      file with the formatted output. If no reformatting is required,
-      the input file will not be touched, and nothing printed.
+      For debugging, dumps the parse tree to stdout and does not update
+      the file or print formatted output.
 
   --stdin
-      Read input from stdin (and write to stdout). Not compatible with
-      --in-place of course.
+      Read input from stdin and write to stdout rather than update
+      a file in-place.
 
 ```
 
 ### **Examples**
 ```
   gn format //some/BUILD.gn
   gn format some\BUILD.gn
   gn format /abspath/some/BUILD.gn
   gn format --stdin
 
@@ skipping 1881 matching lines @@
     configs -= "//tools/mything:settings"
   }
 
 
 ```
 ## **set_sources_assignment_filter**: Set a pattern to filter source files.
 
 ```
   The sources assignment filter is a list of patterns that remove files
   from the list implicitly whenever the "sources" variable is
-  assigned to. This is intended to be used to globally filter out files
-  with platform-specific naming schemes when they don't apply, for
-  example, you may want to filter out all "*_win.cc" files on non-
-  Windows platforms.
+  assigned to. This will do nothing for non-lists.
+
+  This is intended to be used to globally filter out files with
+  platform-specific naming schemes when they don't apply, for example
+  you may want to filter out all "*_win.cc" files on non-Windows
+  platforms.
 
   Typically this will be called once in the master build config script
   to set up the filter for the current platform. Subsequent calls will
   overwrite the previous values.
 
   If you want to bypass the filter and add a file even if it might
   be filtered out, call set_sources_assignment_filter([]) to clear the
   list of filters. This will apply until the current scope exits
 
 ```
@@ skipping 757 matching lines @@
   The copy_bundle_data and compile_xcassets tools only allows the common
   tool substitutions. Both tools are required to create iOS/OS X bundles
   and need only be defined on those platforms.
 
   The copy_bundle_data tool will be called with one source and needs to
   copy (optionally optimizing the data representation) to its output. It
   may be called with a directory as input and it needs to be recursively
   copied.
 
   The compile_xcassets tool will be called with one or more source (each
-  an asset catalog) that needs to be compiled to a single output.
+  an asset catalog) that needs to be compiled to a single output. The
+  following substitutions are avaiable:
+
+    {{inputs}}
+        Expands to the list of .xcassets to use as input to compile the
+        asset catalog.
+
+    {{bundle_product_type}}
+        Expands to the product_type of the bundle that will contain the
+        compiled asset catalog. Usually corresponds to the product_type
+        property of the corresponding create_bundle target.
 
 ```
 
 ### **Separate linking and dependencies for shared libraries**
 
 ```
   Shared libraries are special in that not all changes to them require
   that dependent targets be re-linked. If the shared library is changed
   but no imports or exports are different, dependent code needn't be
   relinked, which can speed up the build.
@@ skipping 55 matching lines @@
 
 ```
 
 ### **Functions and variables**
 
 ```
   tool()
     The tool() function call specifies the commands commands to run for
     a given step. See "gn help tool".
 
-  toolchain_args()
-    List of arguments to pass to the toolchain when invoking this
-    toolchain. This applies only to non-default toolchains. See
-    "gn help toolchain_args" for more.
+  toolchain_args
+    Overrides for build arguments to pass to the toolchain when invoking
+    it. This is a variable of type "scope" where the variable names
+    correspond to variables in declare_args() blocks.
+
+    When you specify a target using an alternate toolchain, the master
+    build configuration file is re-interpreted in the context of that
+    toolchain. toolchain_args allows you to control the arguments
+    passed into this alternate invocation of the build.
+
+    Any default system arguments or arguments passed in via "gn args"
+    will also be passed to the alternate invocation unless explicitly
+    overridden by toolchain_args.
+
+    The toolchain_args will be ignored when the toolchain being defined
+    is the default. In this case, it's expected you want the default
+    argument values.
+
+    See also "gn help buildargs" for an overview of these arguments.
 
   deps
     Dependencies of this toolchain. These dependencies will be resolved
     before any target in the toolchain is compiled. To avoid circular
     dependencies these must be targets defined in another toolchain.
 
     This is expressed as a list of targets, and generally these targets
     will always specify a toolchain:
       deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ]
 
@@ skipping 15 matching lines @@
     data_deps = [ "//plugins:mine(//toolchains:plugin_toolchain)" ]
   The string "//build/toolchains:plugin_toolchain" is a label that
   identifies the toolchain declaration for compiling the sources.
 
   To load a file in an alternate toolchain, GN does the following:
 
    1. Loads the file with the toolchain definition in it (as determined
       by the toolchain label).
    2. Re-runs the master build configuration file, applying the
       arguments specified by the toolchain_args section of the toolchain
-      definition (see "gn help toolchain_args").
+      definition.
    3. Loads the destination build file in the context of the
       configuration file in the previous step.
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   toolchain("plugin_toolchain") {
     tool("cc") {
       command = "gcc {{source}}"
       ...
     }
 
-    toolchain_args() {
+    toolchain_args = {
       is_plugin = true
       is_32bit = true
       is_64bit = false
     }
   }
 
 
 ```
 ## **toolchain_args**: Set build arguments for toolchain build setup.
 
 ```
-  Used inside a toolchain definition to pass arguments to an alternate
-  toolchain's invocation of the build.
+  DEPRECATED. Instead use:
+    toolchain_args = { ... }
 
-  When you specify a target using an alternate toolchain, the master
-  build configuration file is re-interpreted in the context of that
-  toolchain (see "gn help toolchain"). The toolchain_args function
-  allows you to control the arguments passed into this alternate
-  invocation of the build.
-
-  Any default system arguments or arguments passed in on the command-
-  line will also be passed to the alternate invocation unless explicitly
-  overridden by toolchain_args.
-
-  The toolchain_args will be ignored when the toolchain being defined
-  is the default. In this case, it's expected you want the default
-  argument values.
-
-  See also "gn help buildargs" for an overview of these arguments.
-
-```
-
-### **Example**:
-```
-  toolchain("my_weird_toolchain") {
-    ...
-    toolchain_args() {
-      # Override the system values for a generic Posix system.
-      is_win = false
-      is_posix = true
-
-      # Pass this new value for specific setup for my toolchain.
-      is_my_weird_system = true
-    }
-  }
+  See "gn help toolchain" for documentation.
 
 
 ```
 ## **write_file**: Write a file to disk.
 
 ```
   write_file(filename, data)
 
   If data is a list, the list will be written one-item-per-line with no
   quoting or brackets.
@@ skipping 636 matching lines @@
     deps = [ "//foo:bar" ]
     ...
     assert_no_deps = [
       "//evil/*",  # Don't link any code from the evil directory.
       "//foo:test_support",  # This target is also disallowed.
     ]
   }
 
 
 ```
+## **bundle_deps_filter**: [label list] A list of labels that are filtered out.
+
+```
+  A list of target labels.
+
+  This list contains target label patterns that should be filtered out
+  when creating the bundle. Any target matching one of those label will
+  be removed from the dependencies of the create_bundle target.
+
+  This is mostly useful when creating application extension bundle as
+  the application extension has access to runtime resources from the
+  application bundle and thus do not require a second copy.
+
+  See "gn help create_bundle" for more information.
+
+```
+
+### **Example**
+
+```
+  create_bundle("today_extension") {
+    deps = [
+      "//base"
+    ]
+    bundle_root_dir = "$root_out_dir/today_extension.appex"
+    bundle_deps_filter = [
+      # The extension uses //base but does not use any function calling
+      # into third_party/icu and thus does not need the icudtl.dat file.
+      "//third_party/icu:icudata",
+    ]
+  }
+
+
+```
 ## **bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in create_bundle.
 
 ```
   A string corresponding to a path in $root_build_dir.
 
   This string is used by the "create_bundle" target to expand the
   {{bundle_executable_dir}} of the "bundle_data" target it depends on.
   This must correspond to a path under "bundle_root_dir".
 
   See "gn help bundle_root_dir" for examples.
@@ skipping 635 matching lines @@
   propagated across all types of targets, and public_configs
   are always propagated across public deps of all types of targets.
 
   Data dependencies are propagated differently. See
   "gn help data_deps" and "gn help runtime_deps".
 
   See also "public_deps".
 
 
 ```
-## **bundle_deps_filter**: [label list] A list of labels that are filtered out.
-
-```
-  A list of target labels.
-
-  This list contains target label patterns that should be filtered out
-  when creating the bundle. Any target matching one of those label will
-  be removed from the dependencies of the create_bundle target.
-
-  This is mostly useful when creating application extension bundle as
-  the application extension has access to runtime resources from the
-  application bundle and thus do not require a second copy.
-
-  See "gn help create_bundle" for more information.
-
-```
-
-### **Example**
-
-```
-  create_bundle("today_extension") {
-    deps = [
-      "//base"
-    ]
-    bundle_root_dir = "$root_out_dir/today_extension.appex"
-    bundle_deps_filter = [
-      # The extension uses //base but does not use any function calling
-      # into third_party/icu and thus does not need the icudtl.dat file.
-      "//third_party/icu:icudata",
-    ]
-  }
-
-
-```
 ## **include_dirs**: Additional include directories.
 
 ```
   A list of source directories.
 
   The directories in this list will be added to the include path for
   the files in the affected target.
 
 ```
 
@@ skipping 857 matching lines @@
   If specified, arguments from the --args command line flag are used. If
   that flag is not specified, args from previous builds in the build
   directory will be used (this is in the file args.gn in the build
   directory).
 
   Last, for targets being compiled with a non-default toolchain, the
   toolchain overrides are applied. These are specified in the
   toolchain_args section of a toolchain definition. The use-case for
   this is that a toolchain may be building code for a different
   platform, and that it may want to always specify Posix, for example.
-  See "gn help toolchain_args" for more.
+  See "gn help toolchain" for more.
 
   If you specify an override for a build argument that never appears in
   a "declare_args" call, a nonfatal error will be displayed.
 
 ```
 
 ### **Examples**
 
 ```
   gn args out/FooBar
@@ skipping 109 matching lines @@
     "//doom_melon/*",  # Check everything in this subtree.
     "//tools:mind_controlling_ant",  # Check this specific target.
   ]
 
   root = "//:root"
 
   secondary_source = "//build/config/temporary_buildfiles/"
 
 
 ```
-## **GN build language grammar**
+## **Language and grammar for GN build files**
 
 ### **Tokens**
 
 ```
   GN build files are read as sequences of tokens.  While splitting the
   file into tokens, the next token is the longest sequence of characters
   that form a valid token.
 
 ```
 
@@ skipping 59 matching lines @@
 
           \"    U+0022    quotation mark
           \$    U+0024    dollar sign
           \\    U+005C    backslash
 
   All other backslashes represent themselves.
 
   To insert an arbitrary byte value, use $0xFF. For example, to
   insert a newline character: "Line one$0x0ALine two".
 
+  An expansion will evaluate the variable following the '$' and insert
+  a stringified version of it into the result. For example, to concat
+  two path components with a slash separating them:
+    "$var_one/$var_two"
+  Use the "${var_one}" format to be explicitly deliniate the variable
+  for otherwise-ambiguous cases.
+
 ```
 
 ### **Punctuation**
 
 ```
   The following character sequences represent punctuation:
 
           +       +=      ==      !=      (       )
           -       -=      <       <=      [       ]
           !       =       >       >=      {       }
                           &&      ||      .       ,
 
 ```
 
 ### **Grammar**
 
 ```
   The input tokens form a syntax tree following a context-free grammar:
 
       File = StatementList .
 
       Statement     = Assignment | Call | Condition .
-      Assignment    = identifier AssignOp Expr .
+      LValue        = identifier | ArrayAccess | ScopeAccess .
+      Assignment    = LValue AssignOp Expr .
       Call          = identifier "(" [ ExprList ] ")" [ Block ] .
       Condition     = "if" "(" Expr ")" Block
                       [ "else" ( Condition | Block ) ] .
       Block         = "{" StatementList "}" .
       StatementList = { Statement } .
 
-      ArrayAccess = identifier "[" { identifier | integer } "]" .
+      ArrayAccess = identifier "[" Expr "]" .
       ScopeAccess = identifier "." identifier .
       Expr        = UnaryExpr | Expr BinaryOp Expr .
       UnaryExpr   = PrimaryExpr | UnaryOp UnaryExpr .
       PrimaryExpr = identifier | integer | string | Call
-                  | ArrayAccess | ScopeAccess
+                  | ArrayAccess | ScopeAccess | Block
                   | "(" Expr ")"
                   | "[" [ ExprList [ "," ] ] "]" .
       ExprList    = Expr { "," Expr } .
 
       AssignOp = "=" | "+=" | "-=" .
       UnaryOp  = "!" .
       BinaryOp = "+" | "-"                  // highest priority
                | "<" | "<=" | ">" | ">="
                | "==" | "!="
                | "&&"
                | "||" .                     // lowest priority
 
   All binary operators are left-associative.
 
+```
+
+### **Types**
+
+```
+  The GN language is dynamically typed. The following types are used:
+
+   - Boolean: Uses the keywords "true" and "false". There is no
+     implicit conversion between booleans and integers.
+
+   - Integers: All numbers in GN are signed 64-bit integers.
+
+   - Strings: Strings are 8-bit with no enforced encoding. When a string
+     is used to interact with other systems with particular encodings
+     (like the Windows and Mac filesystems) it is assumed to be UTF-8.
+     See "String literals" above for more.
+
+   - Lists: Lists are arbitrary-length ordered lists of values. See
+     "Lists" below for more.
+
+   - Scopes: Scopes are like dictionaries that use variable names for
+     keys. See "Scopes" below for more.
+
+```
+
+### **Lists**
+
+```
+  Lists are created with [] and using commas to separate items:
+
+       mylist = [ 0, 1, 2, "some string" ]
+
+  A comma after the last item is optional. Lists are dereferenced using
+  0-based indexing:
+
+       mylist[0] += 1
+       var = mylist[2]
+
+  Lists can be concatenated using the '+' and '+=' operators. Bare
+  values can not be concatenated with lists, to add a single item,
+  it must be put into a list of length one.
+
+  Items can be removed from lists using the '-' and '-=' operators.
+  This will remove all occurrences of every item in the right-hand list
+  from the left-hand list. It is an error to remove an item not in the
+  list. This is to prevent common typos and to detect dead code that
+  is removing things that no longer apply.
+
+  It is an error to use '=' to replace a nonempty list with another
+  nonempty list. This is to prevent accidentally overwriting data
+  when in most cases '+=' was intended. To overwrite a list on purpose,
+  first assign it to the empty list:
+
+    mylist = []
+    mylist = otherlist
+
+  When assigning to a list named 'sources' using '=' or '+=', list
+  items may be automatically filtered out.
+  See "gn help set_sources_assignment_filter" for more.
+
+```
+
+### **Scopes**
+
+```
+  All execution happens in the context of a scope which holds the
+  current state (like variables). With the exception of loops and
+  conditions, '{' introduces a new scope that has a parent reference to
+  the old scope.
+
+  Variable reads recursively search all nested scopes until the
+  variable is found or there are no more scopes. Variable writes always
+  go into the current scope. This means that after the closing '}'
+  (again excepting loops and conditions), all local variables will be
+  restored to the previous values. This also means that "foo = foo"
+  can do useful work by copying a variable into the current scope that
+  was defined in a containing scope.
+
+  Scopes can also be assigned to variables. Such scopes can be created
+  by functions like exec_script, when invoking a template (the template
+  code refers to the variables set by the invoking code by the
+  implicitly-created "invoker" scope), or explicitly like:
+
+    empty_scope = {}
+    myvalues = {
+      foo = 21
+      bar = "something"
+    }
+
+  Inside such a scope definition can be any GN code including
+  conditionals and function calls. After the close of the scope, it will
+  contain all variables explicitly set by the code contained inside it.
+  After this, the values can be read, modified, or added to:
+
+    myvalues.foo += 2
+    empty_scope.new_thing = [ 1, 2, 3 ]
+
 
 ```
 ## **input_conversion**: Specifies how to transform input to a variable.
 
 ```
   input_conversion is an argument to read_file and exec_script that
   specifies how the result of the read operation should be converted
   into a variable.
 
   "" (the default)
@@ skipping 342 matching lines @@
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--script-executable**: Set the executable used to execute scripts.
 **  \--threads**: Specify number of worker threads.
 **  \--time**: Outputs a summary of how long everything took.
 **  \--tracelog**: Writes a Chrome-compatible trace log to the given file.
 **  -v**: Verbose logging.
 **  \--version**: Prints the GN version number and exits.
 
 ```