[GN] Add support for code signing to "create_bundle" targets.

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 846 matching lines @@
       Lists all variants of the target //base:base (it may be referenced
       in multiple toolchains).
 
 
 ```
 ## **gn path <out_dir> <target_one> <target_two>**
 
 ```
   Finds paths of dependencies between two targets. Each unique path
   will be printed in one group, and groups will be separate by newlines.
-  The two targets can appear in either order: paths will be found going
-  in either direction.
+  The two targets can appear in either order (paths will be found going
+  in either direction).
 
   By default, a single path will be printed. If there is a path with
   only public dependencies, the shortest public path will be printed.
   Otherwise, the shortest path using either public or private
   dependencies will be printed. If --with-data is specified, data deps
   will also be considered. If there are multiple shortest paths, an
   arbitrary one will be selected.
 
 ```
 
+### **Interesting paths**
+
+```
+  In a large project, there can be 100's of millions of unique paths
+  between a very high level and a common low-level target. To make the
+  output more useful (and terminate in a reasonable time), GN will not
+  revisit sub-paths previously known to lead to the target.
+
+```
+
 ### **Options**
 
 ```
   --all
-     Prints all paths found rather than just the first one. Public paths
-     will be printed first in order of increasing length, followed by
-     non-public paths in order of increasing length.
+     Prints all "interesting" paths found rather than just the first
+     one. Public paths will be printed first in order of increasing
+     length, followed by non-public paths in order of increasing length.
 
   --public
      Considers only public paths. Can't be used with --with-data.
 
   --with-data
      Additionally follows data deps. Without this flag, only public and
      private linked deps will be followed. Can't be used with --public.
 
 ```
 
@@ skipping 523 matching lines @@
   put it behind iOS/Mac conditionals.
 
   If a create_bundle is specified as a data_deps for another target, the
   bundle is considered a leaf, and its public and private dependencies
   will not contribute to any data or data_deps. Required runtime
   dependencies should be placed in the bundle. A create_bundle can
   declare its own explicit data and data_deps, however.
 
 ```
 
+### **Code signing**
+
+```
+  Some bundle needs to be code signed as part of the build (on iOS all
+  application needs to be code signed to run on a device). The code
+  signature can be configured via the code_signing_script variable.
+
+  If set, code_signing_script is the path of a script that invoked after
+  all files have been moved into the bundle. The script must not change
+  any file in the bundle, but may add new files.
+
+  If code_signing_script is defined, then code_signing_outputs must also
+  be defined and non-empty to inform when the script needs to be re-run.
+  The code_signing_args will be passed as is to the script (so path have
+  to be rebased) and additional inputs may be listed with the variable
+  code_signing_sources.
+
+```
+
 ### **Variables**
 
 ```
   bundle_root_dir*, bundle_resources_dir*, bundle_executable_dir*,
   bundle_plugins_dir*, deps, data_deps, public_deps, visibility,
-  product_type
+  product_type, code_signing_args, code_signing_script,
+  code_signing_sources, code_signing_outputs
   * = required
 
 ```
 
 ### **Example**
 
 ```
   # Defines a template to create an application. On most platform, this
   # is just an alias for an "executable" target, but on iOS/OS X, it
   # builds an application bundle.
@@ skipping 15 matching lines @@
       }
 
       bundle_data("${app_name}_bundle_info_plist") {
         deps = [ ":${app_name}_generate_info_plist" ]
         sources = [ "$gen_path/Info.plist" ]
         outputs = [ "{{bundle_root_dir}}/Info.plist" ]
       }
 
       executable("${app_name}_generate_executable") {
         forward_variables_from(invoker, "*", [
-                                                "output_name",
-                                                "visibility",
-                                               ])
+                                               "output_name",
+                                               "visibility",
+                                             ])
         output_name =
             rebase_path("$gen_path/$app_name", root_build_dir)
       }
 
-      bundle_data("${app_name}_bundle_executable") {
-        deps = [ ":${app_name}_generate_executable" ]
-        sources = [ "$gen_path/$app_name" ]
-        outputs = [ "{{bundle_executable_dir}}/$app_name" ]
+      code_signing =
+          defined(invoker.code_signing) && invoker.code_signing
+
+      if (is_ios && !code_signing) {
+        bundle_data("${app_name}_bundle_executable") {
+          deps = [ ":${app_name}_generate_executable" ]
+          sources = [ "$gen_path/$app_name" ]
+          outputs = [ "{{bundle_executable_dir}}/$app_name" ]
+        }
       }
 
       create_bundle("${app_name}.app") {
         product_type = "com.apple.product-type.application"
-        deps = [
-          ":${app_name}_bundle_executable",
-          ":${app_name}_bundle_info_plist",
-        ]
         if (is_ios) {
           bundle_root_dir = "${root_build_dir}/$target_name"
           bundle_resources_dir = bundle_root_dir
           bundle_executable_dir = bundle_root_dir
           bundle_plugins_dir = bundle_root_dir + "/Plugins"
         } else {
           bundle_root_dir = "${root_build_dir}/target_name/Contents"
           bundle_resources_dir = bundle_root_dir + "/Resources"
           bundle_executable_dir = bundle_root_dir + "/MacOS"
           bundle_plugins_dir = bundle_root_dir + "/Plugins"
         }
-      }
-
-      group(target_name) {
-        forward_variables_from(invoker, ["visibility"])
-        deps = [ ":${app_name}.app" ]
+        deps = [ ":${app_name}_bundle_info_plist" ]
+        if (is_ios && code_signing) {
+          deps += [ ":${app_name}_generate_executable" ]
+          code_signing_script = "//build/config/ios/codesign.py"
+          code_signing_sources = [
+            invoker.entitlements_path,
+            "$target_gen_dir/$app_name",
+          ]
+          code_signing_outputs = [
+            "$bundle_root_dir/$app_name",
+            "$bundle_root_dir/_CodeSignature/CodeResources",
+            "$bundle_root_dir/embedded.mobileprovision",
+            "$target_gen_dir/$app_name.xcent",
+          ]
+          code_signing_args = [
+            "-i=" + ios_code_signing_identity,
+            "-b=" + rebase_path(
+                "$target_gen_dir/$app_name", root_build_dir),
+            "-e=" + rebase_path(
+                invoker.entitlements_path, root_build_dir),
+            "-e=" + rebase_path(
+                "$target_gen_dir/$app_name.xcent", root_build_dir),
+            rebase_path(bundle_root_dir, root_build_dir),
+          ]
+        } else {
+          deps += [ ":${app_name}_bundle_executable" ]
+        }
       }
     }
   }
 
 
 ```
 ## **declare_args**: Declare build arguments.
 
 ```
   Introduces the given arguments into the current scope. If they are
@@ skipping 2089 matching lines @@
     args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
   }
 
 
 ```
 ## **target_cpu**: The desired cpu architecture for the build.
 
 ```
   This value should be used to indicate the desired architecture for
   the primary objects of the build. It will match the cpu architecture
-  of the default toolchain.
+  of the default toolchain, but not necessarily the current toolchain.
 
   In many cases, this is the same as "host_cpu", but in the case
-  of cross-compiles, this can be set to something different. This 
-  value is different from "current_cpu" in that it can be referenced
-  from inside any toolchain. This value can also be ignored if it is
-  not needed or meaningful for a project.
+  of cross-compiles, this can be set to something different. This
+  value is different from "current_cpu" in that it does not change
+  based on the current toolchain. When writing rules, "current_cpu"
+  should be used rather than "target_cpu" most of the time.
 
   This value is not used internally by GN for any purpose, so it
   may be set to whatever value is needed for the build.
   GN defaults this value to the empty string ("") and the
   configuration files should set it to an appropriate value
   (e.g., setting it to the value of "host_cpu") if it is not
   overridden on the command line or in the args.gn file.
 
   Where practical, use one of the following list of common values:
 
@@ skipping 624 matching lines @@
 
 ```
   source_set("busted_includes") {
     # This target's includes are messed up, exclude it from checking.
     check_includes = false
     ...
   }
 
 
 ```
+## **code_signing_args**: [string list] Arguments passed to code signing script.
+
+```
+  For create_bundle targets, code_signing_args is the list of arguments
+  to pass to the code signing script. Typically you would use source
+  expansion (see "gn help source_expansion") to insert the source file
+  names.
+
+  See also "gn help create_bundle".
+
+
+```
+## **code_signing_outputs**: [file list] Output files for code signing step.
+
+```
+  Outputs from the code signing step of a create_bundle target. Must
+  refer to files in the build directory.
+
+  See also "gn help create_bundle".
+
+
+```
+## **code_signing_script**: [file name] Script for code signing.
+```
+  An absolute or buildfile-relative file name of a Python script to run
+  for a create_bundle target to perform code signing step.
+
+  See also "gn help create_bundle".
+
+
+```
+## **code_signing_sources**: [file list] Sources for code signing step.
+
+```
+  A list of files used as input for code signing script step of a
+  create_bundle target. Non-absolute paths will be resolved relative to
+  the current build file.
+
+  See also "gn help create_bundle".
+
+
+```
 ## **complete_static_lib**: [boolean] Links all deps into a static library.
 
 ```
   A static library normally doesn't include code from dependencies, but
   instead forwards the static libraries and source sets in its deps up
   the dependency chain until a linkable target (an executable or shared
   library) is reached. The final linkable target only links each static
   library once, even if it appears more than once in its dependency
   graph.
 
@@ skipping 1667 matching lines @@
   (possibly on the static library target itself).
 
 ```
 
 ### **Multiple outputs**
 
 ```
   When a tool produces more than one output, only the first output
   is considered. For example, a shared library target may produce a
   .dll and a .lib file on Windows. Only the .dll file will be considered
-  a runtime dependency. This applies only to linker tools, scripts and
-  copy steps with multiple outputs will also get all outputs listed.
+  a runtime dependency. This applies only to linker tools. Scripts and
+  copy steps with multiple outputs will get all outputs listed.
 
 
 ```
 ## **How Source Expansion Works**
 
 ```
   Source expansion is used for the action_foreach and copy target types
   to map source file names to output file names or arguments.
 
   To perform source expansion in the outputs, GN maps every entry in the
@@ skipping 127 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.
 
 ```