[GN]: Support for loadable modules

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 360 matching lines @@
 
   deps
       Show immediate or recursive dependencies. See below for flags that
       control deps printing.
 
   public_configs
   all_dependent_configs
       Shows the labels of configs applied to targets that depend on this
       one (either directly or all of them).
 
+  forward_dependent_configs_from

[brettw, 2015/10/14 17:45:56]

I think this is a merge mistake and that Thiago removed this stuff. Maybe
regenerate the file after you merge (same for the other forward* stuff below).

[Bons, 2015/10/14 18:03:42]

Done.

+      Shows the labels of dependencies for which dependent configs will
+      be pushed to targets depending on the current one.
+
   script
   args
   depfile
       Actions only. The script and related values.
 
   outputs
       Outputs for script and copy target types.
 
   defines       [--blame]
   include_dirs  [--blame]
@@ skipping 627 matching lines @@
    3. Public_configs from a breadth-first traversal of the dependency
       tree in the order that the targets appear in "deps".
    4. All dependent configs from a breadth-first traversal of the
       dependency tree in the order that the targets appear in "deps".
 
 ```
 
 ### **Variables valid in a config definition**:
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
 
 ```
 
 ### **Variables on a target used to apply configs**:
 ```
-  all_dependent_configs, configs, public_configs
+  all_dependent_configs, configs, public_configs,
+  forward_dependent_configs_from
 
 ```
 
 ### **Example**:
 ```
   config("myconfig") {
     includes = [ "include/common" ]
     defines = [ "ENABLE_DOOM_MELON" ]
   }
 
@@ skipping 170 matching lines @@
   exec_script("//foo/bar/myscript.py")
 
 
 ```
 ## **executable**: Declare an executable target.
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
-  Deps: data_deps, deps, public_deps
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
 ## **foreach**: Iterate over a list.
 
 ```
   foreach(<loop_var>, <list>) {
@@ skipping 336 matching lines @@
 
 ```
 ## **group**: Declare a named group of targets.
 
 ```
   This target type allows you to create meta-targets that just collect a
   set of dependencies into one named target. Groups can additionally
   specify configs that apply to their dependents.
 
   Depending on a group is exactly like depending directly on that
-  group's deps.
+  group's deps. Direct dependent configs will get automatically
+  forwarded through the group so you shouldn't need to use
+  "forward_dependent_configs_from.
 
 ```
 
 ### **Variables**
 
 ```
-  Deps: data_deps, deps, public_deps
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
 
 ```
 
 ### **Example**
 
 ```
   group("all") {
     deps = [
       "//project:runner",
@@ skipping 386 matching lines @@
   listing the shared library in its "deps". If you don't want this
   (say you dynamically load the library at runtime), then you should
   depend on the shared library via "data_deps" instead.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
-  Deps: data_deps, deps, public_deps
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
 ## **source_set**: Declare a source set target.
 
 ```
   A source set is a collection of sources that get compiled, but are not
@@ skipping 18 matching lines @@
   final shared library and not from the intermediate targets." There is
   no way to express this concept when linking multiple static libraries
   into a shared library.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
-  Deps: data_deps, deps, public_deps
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
 ## **static_library**: Declare a static library target.
 
 ```
   Make a ".a" / ".lib" file.
 
   If you only need the static library for intermediate results in the
   build, you should consider a source_set instead since it will skip
   the (potentially slow) step of creating the intermediate library file.
 
 ```
 
 ### **Variables**
 
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
-         defines, include_dirs, ldflags, lib_dirs, libs,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
-  Deps: data_deps, deps, public_deps
+  Deps: data_deps, deps, forward_dependent_configs_from, public_deps
   Dependent configs: all_dependent_configs, public_configs
   General: check_includes, configs, data, inputs, output_name,
            output_extension, public, sources, testonly, visibility
 
 
 ```
 ## **target**: Declare an target with the given programmatic type.
 
 ```
   target(target_type_string, target_name_string) { ... }
@@ skipping 427 matching lines @@
         The short name of the current target with no path information,
         or the value of the "output_name" variable if one is specified
         in the target. This will include the "output_prefix" if any.
         Example: "libfoo" for the target named "foo" and an
         output prefix for the linker tool of "lib".
 
   Compiler tools have the notion of a single input and a single output,
   along with a set of compiler-specific flags. The following expansions
   are available:
 
+    {{asmflags}}
     {{cflags}}
     {{cflags_c}}
     {{cflags_cc}}
     {{cflags_objc}}
     {{cflags_objcc}}
     {{defines}}
     {{include_dirs}}
         Strings correspond that to the processed flags/defines/include
         directories specified for the target.
         Example: "--enable-foo --enable-bar"
@@ skipping 686 matching lines @@
 ```
 ## **cflags***: Flags passed to the C compiler.
 
 ```
   A list of strings.
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
-  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
-  These variant-specific versions will be appended to the "cflags".
+  "cflags_cc", "cflags_objc", and "cflags_objcc",
+  respectively.
+
+  These variant-specific versions of cflags* will be appended to the
+  "cflags".
 
 ```
 
 ### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
@@ skipping 11 matching lines @@
 ```
 ## **cflags***: Flags passed to the C compiler.
 
 ```
   A list of strings.
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
-  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
-  These variant-specific versions will be appended to the "cflags".
+  "cflags_cc", "cflags_objc", and "cflags_objcc",
+  respectively.
+
+  These variant-specific versions of cflags* will be appended to the
+  "cflags".
 
 ```
 
 ### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
@@ skipping 11 matching lines @@
 ```
 ## **cflags***: Flags passed to the C compiler.
 
 ```
   A list of strings.
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
-  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
-  These variant-specific versions will be appended to the "cflags".
+  "cflags_cc", "cflags_objc", and "cflags_objcc",
+  respectively.
+
+  These variant-specific versions of cflags* will be appended to the
+  "cflags".
 
 ```
 
 ### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
@@ skipping 11 matching lines @@
 ```
 ## **cflags***: Flags passed to the C compiler.
 
 ```
   A list of strings.
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
-  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
-  These variant-specific versions will be appended to the "cflags".
+  "cflags_cc", "cflags_objc", and "cflags_objcc",
+  respectively.
+
+  These variant-specific versions of cflags* will be appended to the
+  "cflags".
 
 ```
 
 ### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
@@ skipping 11 matching lines @@
 ```
 ## **cflags***: Flags passed to the C compiler.
 
 ```
   A list of strings.
 
   "cflags" are passed to all invocations of the C, C++, Objective C,
   and Objective C++ compilers.
 
   To target one of these variants individually, use "cflags_c",
-  "cflags_cc", "cflags_objc", and "cflags_objcc", respectively.
-  These variant-specific versions will be appended to the "cflags".
+  "cflags_cc", "cflags_objc", and "cflags_objcc",
+  respectively.
+
+  These variant-specific versions of cflags* will be appended to the
+  "cflags".
 
 ```
 
 ### **Ordering of flags and values**
 
 ```
   1. Those set on the current target (not in a config).
   2. Those set on the "configs" on the target in order that the
      configs appear in the list.
   3. Those set on the "all_dependent_configs" on the target in order
@@ skipping 347 matching lines @@
   libraries will be linked into the current target.
 
   These dependencies are private in that it does not grant dependent
   targets the ability to include headers from the dependency, and direct
   dependent configs are not forwarded.
 
   See also "public_deps" and "data_deps".
 
 
 ```
+## **forward_dependent_configs_from**
+
+```
+  A list of target labels.
+
+  DEPRECATED. Use public_deps instead which will have the same effect.
+
+  Exposes the public_configs from a private dependent target as
+  public_configs of the current one. Each label in this list
+  must also be in the deps.
+
+  Generally you should use public_deps instead of this variable to
+  express the concept of exposing a dependency as part of a target's
+  public API. We're considering removing this variable.
+
+```
+
+### **Discussion**
+
+```
+  Sometimes you depend on a child library that exports some necessary
+  configuration via public_configs. If your target in turn exposes the
+  child library's headers in its public headers, it might mean that
+  targets that depend on you won't work: they'll be seeing the child
+  library's code but not the necessary configuration. This list
+  specifies which of your deps' direct dependent configs to expose as
+  your own.
+
+```
+
+### **Examples**
+
+```
+  If we use a given library "a" from our public headers:
+
+    deps = [ ":a", ":b", ... ]
+    forward_dependent_configs_from = [ ":a" ]
+
+  This example makes a "transparent" target that forwards a dependency
+  to another:
+
+    group("frob") {
+      if (use_system_frob) {
+        deps = ":system_frob"
+      } else {
+        deps = "//third_party/fallback_frob"
+      }
+      forward_dependent_configs_from = deps
+    }
+
 
 ```
 ## **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 1270 matching lines @@
 **  -q**: Quiet mode. Don't print output on success.
 **  \--root**: Explicitly specify source root.
 **  \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
 **  \--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.
 
 ```