[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 437 matching lines @@
       Print a dependency tree. By default, duplicates will be elided
       with "..." but when --all and -tree are used together, no
       eliding will be performed.
 
       The "deps", "public_deps", and "data_deps" will all be
       included in the tree.
 
       Tree output can not be used with the filtering or output flags:
       --as, --type, --testonly.
 
-  --type=(action|copy|executable|group|shared_library|source_set|
-          static_library)
+  --type=(action|copy|executable|group|loadable_module|shared_library|
+          source_set|static_library)
       Restrict outputs to targets matching the given type. If
       unspecified, no filtering will be performed.
 
 ```
 
 ### **Note**
 
 ```
   This command will show the full name of directories and source files,
   but when directories and source paths are written to the build file,
@@ skipping 117 matching lines @@
       Matches all toolchains. When set, if the label pattern does not
       specify an explicit toolchain, labels from all toolchains will be
       matched. When unset, only targets in the default toolchain will
       be matched unless an explicit toolchain in the label is set.
 
   --testonly=(true|false)
       Restrict outputs to targets with the testonly flag set
       accordingly. When unspecified, the target's testonly flags are
       ignored.
 
-  --type=(action|copy|executable|group|shared_library|source_set|
-          static_library)
+  --type=(action|copy|executable|group|loadable_module|shared_library|
+          source_set|static_library)
       Restrict outputs to targets matching the given type. If
       unspecified, no filtering will be performed.
 
 ```
 
 ### **Examples**
 
 ```
   gn ls out/Debug
       Lists all targets in the default toolchain.
@@ skipping 124 matching lines @@
       ignored.
 
   --tree
       Outputs a reverse dependency tree from the given target.
       Duplicates will be elided. Combine with --all to see a full
       dependency tree.
 
       Tree output can not be used with the filtering or output flags:
       --as, --type, --testonly.
 
-  --type=(action|copy|executable|group|shared_library|source_set|
-          static_library)
+  --type=(action|copy|executable|group|loadable_module|shared_library|
+          source_set|static_library)
       Restrict outputs to targets matching the given type. If
       unspecified, no filtering will be performed.
 
 ```
 
 ### **Examples (target input)**
 
 ```
   gn refs out/Debug //tools/gn:gn
       Find all targets depending on the given exact target name.
@@ skipping 263 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
 
 ```
 
@@ skipping 57 matching lines @@
 ## **declare_args**: Declare build arguments.
 
 ```
   Introduces the given arguments into the current scope. If they are
   not specified on the command line or in a toolchain's arguments,
   the default values given in the declare_args block will be used.
   However, these defaults will not override command-line values.
 
   See also "gn help buildargs" for an overview.
 
+  The precise behavior of declare args is:
+
+   1. The declare_arg block executes. Any variables in the enclosing
+      scope are available for reading.
+
+   2. At the end of executing the block, any variables set within that
+      scope are saved globally as build arguments, with their current
+      values being saved as the "default value" for that argument.
+
+   3. User-defined overrides are applied. Anything set in "gn args"
+      now overrides any default values. The resulting set of variables
+      is promoted to be readable from the following code in the file.
+
+  This has some ramifications that may not be obvious:
+
+    - You should not perform difficult work inside a declare_args block
+      since this only sets a default value that may be discarded. In
+      particular, don't use the result of exec_script() to set the
+      default value. If you want to have a script-defined default, set
+      some default "undefined" value like [], "", or -1, and after
+      the declare_args block, call exec_script if the value is unset by
+      the user.
+
+    - Any code inside of the declare_args block will see the default
+      values of previous variables defined in the block rather than
+      the user-overridden value. This can be surprising because you will
+      be used to seeing the overridden value. If you need to make the
+      default value of one arg dependent on the possibly-overridden
+      value of another, write two separate declare_args blocks:
+
+        declare_args() {
+          enable_foo = true
+        }
+        declare_args() {
+          # Bar defaults to same user-overridden state as foo.
+          enable_bar = enable_foo
+        }
+
 ```
 
-### **Example**:
+### **Example**
+
 ```
   declare_args() {
     enable_teleporter = true
     enable_doom_melon = false
   }
 
   If you want to override the (default disabled) Doom Melon:
     gn --args="enable_doom_melon=true enable_teleporter=false"
   This also sets the teleporter, but it's already defaulted to on so
   it will have no effect.
@@ skipping 97 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
   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.
 
@@ skipping 338 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. 
 
 ```
 
 ### **Variables**
 
 ```
   Deps: data_deps, deps, public_deps
   Dependent configs: all_dependent_configs, public_configs
 
 ```
@@ skipping 42 matching lines @@
 ### **Examples**:
 
 ```
   import("//build/rules/idl_compilation_rule.gni")
 
   # Looks in the current directory.
   import("my_vars.gni")
 
 
 ```
+## **loadable_module**: Declare a loadable module target.
+
+```
+  This target type allows you to create an object file that is (and can
+  only be) loaded and unloaded at runtime.
+
+  A loadable module will be specified on the linker line for targets
+  listing the loadable module in its "deps". If you don't want this
+  (if you don't need to dynamically load the library at runtime), then
+  you should use a "shared_library" target type instead.
+
+```
+
+### **Variables**
+
+```
+  Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
+         asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
+         precompiled_header, precompiled_source
+  Deps: data_deps, deps, public_deps
+  Dependent configs: all_dependent_configs, public_configs
+  General: check_includes, configs, data, inputs, output_name,
+           output_extension, public, sources, testonly, visibility
+
+
+```
 ## **print**: Prints to the console.
 
 ```
   Prints all arguments to the console separated by spaces. A newline is
   automatically appended to the end.
 
   This function is intended for debugging. Note that build files are run
   in parallel so you may get interleaved prints. A buildfile may also
   be executed more than once in parallel in the context of different
   toolchains so the prints from one file may be duplicated or
@@ skipping 323 matching lines @@
   # Will print [ "a.cc" ]. b_win one was filtered out.
 
 
 ```
 ## **shared_library**: Declare a shared library target.
 
 ```
   A shared library will be specified on the linker line for targets
   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.
+  depend on the shared library via "data_deps" or, on Darwin
+  platforms, use a "loadable_module" target type 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
   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.
 
@@ skipping 20 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
   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
   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.
 
@@ skipping 312 matching lines @@
         produces a ".lib" import library:
           outputs = [
             "{{root_out_dir}}/{{target_output_name}}{{output_extension}}",
             "{{root_out_dir}}/{{target_output_name}}.lib",
           ]
 
     link_output  [string with substitutions]
     depend_output  [string with substitutions]
         Valid for: "solink" only (optional)
 
-        These two files specify whch of the outputs from the solink
+        These two files specify which of the outputs from the solink
         tool should be used for linking and dependency tracking. These
         should match entries in the "outputs". If unspecified, the
         first item in the "outputs" array will be used for both. See
         "Separate linking and dependencies for shared libraries"
         below for more.
 
         On Windows, where the tools produce a .dll shared library and
         a .lib import library, you will want both of these to be the
         import library. On Linux, if you're not doing the separate
         linking/dependency optimization, both of these should be the
@@ skipping 96 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".
 
 
 ```
-
-```
 ## **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 1056 matching lines @@
 ## **Runtime dependencies**
 
 ```
   Runtime dependencies of a target are exposed via the "runtime_deps"
   category of "gn desc" (see "gn help desc") or they can be written
   at build generation time via "--runtime-deps-list-file"
   (see "gn help --runtime-deps-list-file").
 
   To a first approximation, the runtime dependencies of a target are
   the set of "data" files, data directories, and the shared libraries
-  from all transitive dependencies. Executables and shared libraries are
-  considered runtime dependencies of themselves.
+  from all transitive dependencies. Executables, shared libraries, and
+  loadable modules are considered runtime dependencies of themselves.
 
 ```
 
 ### **Executables**
 
 ```
   Executable targets and those executable targets' transitive
   dependencies are not considered unless that executable is listed in
   "data_deps". Otherwise, GN assumes that the executable (and
   everything it requires) is a build-time dependency only.
@@ skipping 190 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.
 
 ```