GN: Don't write ldflags and libs when unneeded.

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 514 matching lines @@
   gn format //some/BUILD.gn
   gn format some\BUILD.gn
   gn format /abspath/some/BUILD.gn
   gn format --stdin
 
 
 ```
 ## **gn gen**: Generate ninja files.
 
 ```
-  gn gen <out_dir>
+  gn gen [--ide=<ide_name>] <out_dir>
 
   Generates ninja files from the current tree and puts them in the given
   output directory.
 
   The output directory can be a source-repo-absolute path name such as:
       //out/foo
   Or it can be a directory relative to the current directory such as:
       out/foo
 
+  --ide=<ide_name>
+    Also generate files for an IDE. Currently supported values:
+      'vs' - Visual Studio project/solution files.
+
   See "gn help switches" for the common command-line switches.
 
 
 ```
 ## **gn help <anything>**
 ```
   Yo dawg, I heard you like help on your help so I put help on the help
   in the help.
 
 
@@ skipping 478 matching lines @@
    1. The values specified directly on the target (rather than using a
       config.
    2. The configs specified in the target's "configs" list, in order.
    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**:
+### **Variables valid in a config definition**
+
 ```
   Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
          asmflags, defines, include_dirs, ldflags, lib_dirs, libs,
          precompiled_header, precompiled_source
+  Nested configs: configs
 
 ```
 
-### **Variables on a target used to apply configs**:
+### **Variables on a target used to apply configs**
+
 ```
   all_dependent_configs, configs, public_configs
 
 ```
 
-### **Example**:
+### **Example**
+
 ```
   config("myconfig") {
     includes = [ "include/common" ]
     defines = [ "ENABLE_DOOM_MELON" ]
   }
 
   executable("mything") {
     configs = [ ":myconfig" ]
   }
 
@@ skipping 315 matching lines @@
   }
 
   # This is a template around either a target whose type depends on a
   # global variable. It forwards all values from the invoker.
   template("my_wrapper") {
     target(my_wrapper_target_type, target_name) {
       forward_variables_from(invoker, "*")
     }
   }
 
-  # A template that wraps another. It adds behavior based on one
+  # A template that wraps another. It adds behavior based on one 
   # variable, and forwards all others to the nested target.
   template("my_ios_test_app") {
     ios_test_app(target_name) {
       forward_variables_from(invoker, "*", ["test_bundle_name"])
       if (!defined(extra_substitutions)) {
         extra_substitutions = []
       }
       extra_substitutions += [ "BUNDLE_ID_TEST_NAME=$test_bundle_name" ]
     }
   }
@@ skipping 464 matching lines @@
 
   If you want to convert a file path to be source-absolute (that is,
   beginning with a double slash like "//foo/bar"), you should use
   the get_path_info() function. This function won't work because it will
   always make relative paths, and it needs to support making paths
   relative to the source root, so can't also generate source-absolute
   paths without more special-cases.
 
 ```
 
-### **Arguments**:
+### **Arguments**
 
 ```
   input
       A string or list of strings representing file or directory names
       These can be relative paths ("foo/bar.txt"), system absolute
       paths ("/foo/bar.txt"), or source absolute paths
       ("//foo/bar.txt").
 
   new_base
       The directory to convert the paths to be relative to. This can be
@@ skipping 14 matching lines @@
 ```
 
 ### **Return value**
 
 ```
   The return value will be the same type as the input value (either a
   string or a list of strings). All relative and source-absolute file
   names will be converted to be relative to the requested output
   System-absolute paths will be unchanged.
 
+  Whether an output path will end in a slash will match whether the
+  corresponding input path ends in a slash. It will return "." or
+  "./" (depending on whether the input ends in a slash) to avoid
+  returning empty strings. This means if you want a root path
+  ("//" or "/") not ending in a slash, you can add a dot ("//.").
+
 ```
 
 ### **Example**
 
 ```
   # Convert a file in the current directory to be relative to the build
   # directory (the current dir when executing compilers and scripts).
   foo = rebase_path("myfile.txt", root_build_dir)
   # might produce "../../project/myfile.txt".
 
@@ skipping 1422 matching lines @@
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      more than once, only the first occurance will be used.
   6. public_configs pulled from dependencies, in the order of the
      "deps" list. If a dependency is public, they will be applied
      recursively.
 
 
 ```
+## **assert_no_deps**: Ensure no deps on these targets.
+
+```
+  A list of label patterns.
+
+  This list is a list of patterns that must not match any of the
+  transitive dependencies of the target. These include all public,
+  private, and data dependencies, and cross shared library boundaries.
+  This allows you to express that undesirable code isn't accidentally
+  added to downstream dependencies in a way that might otherwise be
+  difficult to notice.
+
+  Checking does not cross executable boundaries. If a target depends on
+  an executable, it's assumed that the executable is a tool that is
+  producing part of the build rather than something that is linked and
+  distributed. This allows assert_no_deps to express what is distributed
+  in the final target rather than depend on the internal build steps
+  (which may include non-distributable code).
+
+  See "gn help label_pattern" for the format of the entries in the
+  list. These patterns allow blacklisting individual targets or whole
+  directory hierarchies.
+
+  Sometimes it is desirable to enforce that many targets have no
+  dependencies on a target or set of targets. One efficient way to
+  express this is to create a group with the assert_no_deps rule on
+  it, and make that group depend on all targets you want to apply that
+  assertion to.
+
+```
+
+### **Example**
+
+```
+  executable("doom_melon") {
+    deps = [ "//foo:bar" ]
+    ...
+    assert_no_deps = [
+      "//evil/*",  # Don't link any code from the evil directory.
+      "//foo:test_support",  # This target is also disallowed.
+    ]
+  }
+
+
+```
 ## **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",
@@ skipping 711 matching lines @@
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      more than once, only the first occurance will be used.
   6. public_configs pulled from dependencies, in the order of the
      "deps" list. If a dependency is public, they will be applied
      recursively.
 
+  For "libs" and "lib_dirs" only, the values propagated from
+  dependencies (as described above) are applied last assuming they
+  are not already in the list.
+
 ```
 
 ### **Example**
 
 ```
   lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
 
 
 ```
 ## **libs**: Additional libraries to link.
 
 ```
-  A list of strings.
+  A list of library names or library paths.
 
-  These files will be passed to the linker, which will generally search
-  the library include path. Unlike a normal list of files, they will be
-  passed to the linker unmodified rather than being treated as file
-  names relative to the current build file. Generally you would set
-  the "lib_dirs" so your library is found. If you need to specify
-  a path, you can use "rebase_path" to convert a path to be relative
-  to the build directory.
-
-  When constructing the linker command, the "lib_prefix" attribute of
-  the linker tool in the current toolchain will be prepended to each
-  library. So your BUILD file should not specify the switch prefix
-  (like "-l").
-
-  Libraries ending in ".framework" will be special-cased: the switch
-  "-framework" will be prepended instead of the lib_prefix, and the
-  ".framework" suffix will be trimmed. This is to support the way Mac
-  links framework dependencies.
+  These libraries will be linked into the final binary (executable or
+  shared library) containing the current target.
 
   libs and lib_dirs work differently than other flags in two respects.
   First, then are inherited across static library boundaries until a
   shared library or executable target is reached. Second, they are
   uniquified so each one is only passed once (the first instance of it
   will be the one used).
 
 ```
 
+### **Types of libs**
+
+```
+  There are several different things that can be expressed in libs:
+
+  File paths
+      Values containing '/' will be treated as references to files in
+      the checkout. They will be rebased to be relative to the build
+      directory and specified in the "libs" for linker tools. This
+      facility should be used for libraries that are checked in to the
+      version control. For libraries that are generated by the build,
+      use normal GN deps to link them.
+
+  System libraries
+      Values not containing '/' will be treated as system library names.
+      These will be passed unmodified to the linker and prefixed with
+      the "lib_prefix" attribute of the linker tool. Generally you
+      would set the "lib_dirs" so the given library is found. Your
+      BUILD.gn file should not specify the switch (like "-l"): this
+      will be encoded in the "lib_prefix" of the tool.
+
+  Apple frameworks
+      System libraries ending in ".framework" will be special-cased:
+      the switch "-framework" will be prepended instead of the
+      lib_prefix, and the ".framework" suffix will be trimmed. This is
+      to support the way Mac links framework dependencies.
+
+```
+
 ### **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
      that the configs appear in the list.
   4. Those set on the "public_configs" on the target in order that
      those configs appear in the list.
   5. all_dependent_configs pulled from dependencies, in the order of
      the "deps" list. This is done recursively. If a config appears
      more than once, only the first occurance will be used.
   6. public_configs pulled from dependencies, in the order of the
      "deps" list. If a dependency is public, they will be applied
      recursively.
 
+  For "libs" and "lib_dirs" only, the values propagated from
+  dependencies (as described above) are applied last assuming they
+  are not already in the list.
+
 ```
 
 ### **Examples**
 
 ```
   On Windows:
     libs = [ "ctl3d.lib" ]
+
   On Linux:
     libs = [ "ld" ]
 
 
 ```
 ## **output_extension**: Value to use for the output's file extension.
 
 ```
   Normally the file extension for a target is based on the target
   type and the operating system, but in rare cases you will need to
@@ skipping 685 matching lines @@
 
 ### **String literals**
 
 ```
   A string literal represents a string value consisting of the quoted
   characters with possible escape sequences and variable expansions.
 
       string           = `"` { char | escape | expansion } `"` .
       escape           = `\` ( "$" | `"` | char ) .
       BracketExpansion = "{" ( identifier | ArrayAccess | ScopeAccess ) "}" .
-      expansion        = "$" ( identifier | BracketExpansion ) .
+      Hex              = "0x" [0-9A-Fa-f][0-9A-Fa-f]
+      expansion        = "$" ( identifier | BracketExpansion | Hex ) .
       char             = /* any character except "$", `"`, or newline */ .
 
   After a backslash, certain sequences represent special characters:
 
           \"    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".
+
 ```
 
 ### **Punctuation**
 
 ```
   The following character sequences represent punctuation:
 
           +       +=      ==      !=      (       )
           -       -=      <       <=      [       ]
           !       =       >       >=      {       }
@@ skipping 346 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.
 
 ```