Add an output_dir override to GN.

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 2712 matching lines @@
 ```
 
 ### **Tool variables**
 
 ```
     command  [string with substitutions]
         Valid for: all tools (required)
 
         The command to run.
 
+    default_output_dir  [string with substitutions]
+        Valid for: linker tools
+
+        Default directory name for the output file relative to the
+        root_build_dir. It can contain other substitution patterns.
+        This will be the default value for the {{output_dir}} expansion
+        (discussed below) but will be overridden by the "output_dir"
+        variable in a target, if one is specified.
+
+        GN doesn't do anything with this string other than pass it
+        along, potentially with target-specific overrides. It is the
+        tool's job to use the expansion so that the files will be in
+        the right place.
+
     default_output_extension  [string]
         Valid for: linker tools
 
         Extension for the main output of a linkable tool. It includes
         the leading dot. This will be the default value for the
         {{output_extension}} expansion (discussed below) but will be
         overridden by by the "output extension" variable in a target,
         if one is specified. Empty string means no extension.
 
         GN doesn't actually do anything with this extension other than
         pass it along, potentially with target-specific overrides. One
         would typically use the {{output_extension}} value in the
         "outputs" to read this value.
 
         Example: default_output_extension = ".exe"
 
-    depfile  [string]
+    depfile  [string with substitutions]
         Valid for: compiler tools (optional)
 
         If the tool can write ".d" files, this specifies the name of
         the resulting file. These files are used to list header file
         dependencies (or other implicit input dependencies) that are
         discovered at build time. See also "depsformat".
 
         Example: depfile = "{{output}}.d"
 
     depsformat  [string]
@@ skipping 41 matching lines @@
         runtime_link_output. Otherwise, the first entry in the
         outputs list should always be the main output which will be
         linked to.
 
         Example for a compiler tool that produces .obj files:
           outputs = [
             "{{source_out_dir}}/{{source_name_part}}.obj"
           ]
 
         Example for a linker tool that produces a .dll and a .lib. The
-        use of {{output_extension}} rather than hardcoding ".dll"
-        allows the extension of the library to be overridden on a
-        target-by-target basis, but in this example, it always
-        produces a ".lib" import library:
+        use of {{target_output_name}}, {{output_extension}} and
+        {{output_dir}} allows the target to override these values.
           outputs = [
-            "{{root_out_dir}}/{{target_output_name}}{{output_extension}}",
-            "{{root_out_dir}}/{{target_output_name}}.lib",
+            "{{output_dir}}/{{target_output_name}}{{output_extension}}",
+            "{{output_dir}}/{{target_output_name}}.lib",
           ]
 
     link_output  [string with substitutions]
     depend_output  [string with substitutions]
     runtime_link_output  [string with substitutions]
         Valid for: "solink" only (optional)
 
         These three 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 all. See
         "Separate linking and dependencies for shared libraries"
-        below for more.  If link_output is set but runtime_link_output
+        below for more. If link_output is set but runtime_link_output
         is not set, runtime_link_output defaults to link_output.
 
         On Windows, where the tools produce a .dll shared library and
         a .lib import library, you will want the first two to be the
         import library and the third one to be the .dll file.
         On Linux, if you're not doing the separate linking/dependency
         optimization, all of these should be the .so output.
 
     output_prefix  [string]
         Valid for: Linker tools (optional)
@@ skipping 89 matching lines @@
     {{output}}
         The relative path and name of the output(s) of the current
         build step. If there is more than one output, this will expand
         to a list of all of them.
         Example: "out/base/my_file.o"
 
     {{target_gen_dir}}
     {{target_out_dir}}
         The directory of the generated file and output directories,
         respectively, for the current target. There is no trailing
-        slash.
+        slash. See also {{output_dir}} for linker tools.
         Example: "out/base/test"
 
     {{target_output_name}}
         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.
         See also {{label_name}}.
         Example: "libfoo" for the target named "foo" and an
         output prefix for the linker tool of "lib".
 
@@ skipping 62 matching lines @@
     {{libs}}
         Expands to the list of system libraries to link to. Each will
         be prefixed by the "lib_prefix".
 
         As a special case to support Mac, libraries with names ending in
         ".framework" will be added to the {{libs}} with "-framework"
         preceeding it, and the lib prefix will be ignored.
 
         Example: "-lfoo -lbar"
 
+    {{output_dir}}
+        The value of the "output_dir" variable in the target, or the
+        the value of the "default_output_dir" value in the tool if the
+        target does not override the output directory. This will be
+        relative to the root_build_dir and will not end in a slash.
+        Will be "." for output to the root_build_dir.
+
+        This is subtly different than {{target_out_dir}} which is
+        defined by GN based on the target's path and not overridable.
+        {{output_dir}} is for the final output, {{target_out_dir}} is
+        generally for object files and other outputs.
+
+        Usually {{output_dir}} would be defined in terms of either
+        {{target_out_dir}} or {{root_out_dir}}
+
     {{output_extension}}
         The value of the "output_extension" variable in the target,
         or the value of the "default_output_extension" value in the
         tool if the target does not specify an output extension.
         Example: ".so"
 
     {{solibs}}
         Extra libraries from shared library dependencide not specified
         in the {{inputs}}. This is the list of link_output files from
         shared libraries (if the solink tool specifies a "link_output"
@@ skipping 35 matching lines @@
 
   You will need to specify
     restat = true
   in the linker tool to make this work, so Ninja will detect if the
   timestamp of the dependency file has changed after linking (otherwise
   it will always assume that running a command updates the output):
 
     tool("solink") {
       command = "..."
       outputs = [
-        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}",
-        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC",
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}",
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC",
       ]
       link_output =
-        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}"
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}"
       depend_output =
-        "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC"
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC"
       restat = true
     }
 
 ```
 
 ### **Example**
 
 ```
   toolchain("my_toolchain") {
     # Put these at the top to apply to all tools below.
@@ skipping 1558 matching lines @@
 
 ```
   On Windows:
     libs = [ "ctl3d.lib" ]
 
   On Linux:
     libs = [ "ld" ]
 
 
 ```
+## **output_dir**: [directory] Directory to put output file in.
+
+```
+  For library and executable targets, overrides the directory for the
+  final output. This must be in the root_build_dir or a child thereof.
+
+  This should generally be in the root_out_dir or a subdirectory thereof
+  (the root_out_dir will be the same as the root_build_dir for the
+  default toolchain, and will be a subdirectory for other toolchains).
+  Not putting the output in a subdirectory of root_out_dir can result
+  in collisions between different toolchains, so you will need to take
+  steps to ensure that your target is only present in one toolchain.
+
+  Normally the toolchain specifies the output directory for libraries
+  and executables (see "gn help tool"). You will have to consult that
+  for the default location. The default location will be used if
+  output_dir is undefined or empty.
+
+```
+
+### **Example**
+
+```
+  shared_library("doom_melon") {
+    output_dir = "$root_out_dir/plugin_libs"
+    ...
+  }
+
+
+```
 ## **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
   override the name (for example to use "libfreetype.so.6" instead
   of libfreetype.so on Linux).
 
   This value should not include a leading dot. If undefined, the default
   specified on the tool will be used. If set to the empty string, no
@@ skipping 1044 matching lines @@
   sources.
 
   See "gn help copy" and "gn help action_foreach" for more on how
   this is applied.
 
 ```
 
 ### **Placeholders**
 
 ```
+  This section discusses only placeholders for actions. There are other
+  placeholders used in the definition of tools. See "gn help tool" for
+  those.
+
   {{source}}
       The name of the source file including directory (*). This will
       generally be used for specifying inputs to a script in the
       "args" variable.
         "//foo/bar/baz.txt" => "../../foo/bar/baz.txt"
 
   {{source_file_part}}
       The file part of the source including the extension.
         "//foo/bar/baz.txt" => "baz.txt"
 
@@ skipping 92 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.
 
 ```