Add an output_dir override to GN.

tools/gn/function_toolchain.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include <algorithm>
 #include <limits>
 #include <utility>
 
 #include "tools/gn/err.h"
 #include "tools/gn/functions.h"
@@ skipping 400 matching lines @@
     "      \"copy_bundle_data\": [iOS, OS X] Tool to copy files in a bundle.\n"
     "      \"compile_xcassets\": [iOS, OS X] Tool to compile asset catalogs.\n"
     "\n"
     "Tool variables\n"
     "\n"
     "    command  [string with substitutions]\n"
     "        Valid for: all tools (required)\n"
     "\n"
     "        The command to run.\n"
     "\n"
+    "    default_output_dir  [string with substitutions]\n"
+    "        Valid for: linker tools\n"
+    "\n"
+    "        Default directory name for the output file relative to the\n"
+    "        root_build_dir. It can contain other substitution patterns.\n"
+    "        This will be the default value for the {{output_dir}} expansion\n"
+    "        (discussed below) but will be overridden by the \"output_dir\"\n"
+    "        variable in a target, if one is specified.\n"
+    "\n"
+    "        GN doesn't do anything with this string other than pass it\n"
+    "        along, potentially with target-specific overrides. It is the\n"
+    "        tool's job to use the expansion so that the files will be in\n"
+    "        the right place.\n"
+    "\n"
     "    default_output_extension  [string]\n"
     "        Valid for: linker tools\n"
     "\n"
     "        Extension for the main output of a linkable tool. It includes\n"
     "        the leading dot. This will be the default value for the\n"
     "        {{output_extension}} expansion (discussed below) but will be\n"
     "        overridden by by the \"output extension\" variable in a target,\n"
     "        if one is specified. Empty string means no extension.\n"
     "\n"
     "        GN doesn't actually do anything with this extension other than\n"
     "        pass it along, potentially with target-specific overrides. One\n"
     "        would typically use the {{output_extension}} value in the\n"
     "        \"outputs\" to read this value.\n"
     "\n"
     "        Example: default_output_extension = \".exe\"\n"
     "\n"
-    "    depfile  [string]\n"
+    "    depfile  [string with substitutions]\n"
     "        Valid for: compiler tools (optional)\n"
     "\n"
     "        If the tool can write \".d\" files, this specifies the name of\n"
     "        the resulting file. These files are used to list header file\n"
     "        dependencies (or other implicit input dependencies) that are\n"
     "        discovered at build time. See also \"depsformat\".\n"
     "\n"
     "        Example: depfile = \"{{output}}.d\"\n"
     "\n"
     "    depsformat  [string]\n"
@@ skipping 41 matching lines @@
     "        runtime_link_output. Otherwise, the first entry in the\n"
     "        outputs list should always be the main output which will be\n"
     "        linked to.\n"
     "\n"
     "        Example for a compiler tool that produces .obj files:\n"
     "          outputs = [\n"
     "            \"{{source_out_dir}}/{{source_name_part}}.obj\"\n"
     "          ]\n"
     "\n"
     "        Example for a linker tool that produces a .dll and a .lib. The\n"
-    "        use of {{output_extension}} rather than hardcoding \".dll\"\n"
-    "        allows the extension of the library to be overridden on a\n"
-    "        target-by-target basis, but in this example, it always\n"
-    "        produces a \".lib\" import library:\n"
+    "        use of {{target_output_name}}, {{output_extension}} and\n"
+    "        {{output_dir}} allows the target to override these values.\n"
     "          outputs = [\n"
-    "            \"{{root_out_dir}}/{{target_output_name}}"
+    "            \"{{output_dir}}/{{target_output_name}}"
                      "{{output_extension}}\",\n"
-    "            \"{{root_out_dir}}/{{target_output_name}}.lib\",\n"
+    "            \"{{output_dir}}/{{target_output_name}}.lib\",\n"
     "          ]\n"
     "\n"
     "    link_output  [string with substitutions]\n"
     "    depend_output  [string with substitutions]\n"
     "    runtime_link_output  [string with substitutions]\n"
     "        Valid for: \"solink\" only (optional)\n"
     "\n"
     "        These three files specify which of the outputs from the solink\n"
     "        tool should be used for linking and dependency tracking. These\n"
     "        should match entries in the \"outputs\". If unspecified, the\n"
     "        first item in the \"outputs\" array will be used for all. See\n"
     "        \"Separate linking and dependencies for shared libraries\"\n"
-    "        below for more.  If link_output is set but runtime_link_output\n"
+    "        below for more. If link_output is set but runtime_link_output\n"
     "        is not set, runtime_link_output defaults to link_output.\n"
     "\n"
     "        On Windows, where the tools produce a .dll shared library and\n"
     "        a .lib import library, you will want the first two to be the\n"
     "        import library and the third one to be the .dll file.\n"
     "        On Linux, if you're not doing the separate linking/dependency\n"
     "        optimization, all of these should be the .so output.\n"
     "\n"
     "    output_prefix  [string]\n"
     "        Valid for: Linker tools (optional)\n"
@@ skipping 87 matching lines @@
     "    {{output}}\n"
     "        The relative path and name of the output(s) of the current\n"
     "        build step. If there is more than one output, this will expand\n"
     "        to a list of all of them.\n"
     "        Example: \"out/base/my_file.o\"\n"
     "\n"
     "    {{target_gen_dir}}\n"
     "    {{target_out_dir}}\n"
     "        The directory of the generated file and output directories,\n"
     "        respectively, for the current target. There is no trailing\n"
-    "        slash.\n"
+    "        slash. See also {{output_dir}} for linker tools.\n"
     "        Example: \"out/base/test\"\n"
     "\n"
     "    {{target_output_name}}\n"
     "        The short name of the current target with no path information,\n"
     "        or the value of the \"output_name\" variable if one is specified\n"
     "        in the target. This will include the \"output_prefix\" if any.\n"
     "        See also {{label_name}}.\n"
     "        Example: \"libfoo\" for the target named \"foo\" and an\n"
     "        output prefix for the linker tool of \"lib\".\n"
     "\n"
@@ skipping 62 matching lines @@
     "    {{libs}}\n"
     "        Expands to the list of system libraries to link to. Each will\n"
     "        be prefixed by the \"lib_prefix\".\n"
     "\n"
     "        As a special case to support Mac, libraries with names ending in\n"
     "        \".framework\" will be added to the {{libs}} with \"-framework\"\n"
     "        preceeding it, and the lib prefix will be ignored.\n"
     "\n"
     "        Example: \"-lfoo -lbar\"\n"
     "\n"
+    "    {{output_dir}}\n"
+    "        The value of the \"output_dir\" variable in the target, or the\n"
+    "        the value of the \"default_output_dir\" value in the tool if the\n"
+    "        target does not override the output directory. This will be\n"
+    "        relative to the root_build_dir and will not end in a slash.\n"
+    "        Will be \".\" for output to the root_build_dir.\n"
+    "\n"
+    "        This is subtly different than {{target_out_dir}} which is\n"
+    "        defined by GN based on the target's path and not overridable.\n"
+    "        {{output_dir}} is for the final output, {{target_out_dir}} is\n"
+    "        generally for object files and other outputs.\n"
+    "\n"
+    "        Usually {{output_dir}} would be defined in terms of either\n"
+    "        {{target_out_dir}} or {{root_out_dir}}\n"
+    "\n"
     "    {{output_extension}}\n"
     "        The value of the \"output_extension\" variable in the target,\n"
     "        or the value of the \"default_output_extension\" value in the\n"
     "        tool if the target does not specify an output extension.\n"
     "        Example: \".so\"\n"
     "\n"
     "    {{solibs}}\n"
     "        Extra libraries from shared library dependencide not specified\n"
     "        in the {{inputs}}. This is the list of link_output files from\n"
     "        shared libraries (if the solink tool specifies a \"link_output\"\n"
@@ skipping 32 matching lines @@
     "\n"
     "  You will need to specify\n"
     "    restat = true\n"
     "  in the linker tool to make this work, so Ninja will detect if the\n"
     "  timestamp of the dependency file has changed after linking (otherwise\n"
     "  it will always assume that running a command updates the output):\n"
     "\n"
     "    tool(\"solink\") {\n"
     "      command = \"...\"\n"
     "      outputs = [\n"
-    "        \"{{root_out_dir}}/{{target_output_name}}{{output_extension}}\",\n"
-    "        \"{{root_out_dir}}/{{target_output_name}}"
+    "        \"{{output_dir}}/{{target_output_name}}{{output_extension}}\",\n"
+    "        \"{{output_dir}}/{{target_output_name}}"
                  "{{output_extension}}.TOC\",\n"
     "      ]\n"
     "      link_output =\n"
-    "        \"{{root_out_dir}}/{{target_output_name}}{{output_extension}}\"\n"
+    "        \"{{output_dir}}/{{target_output_name}}{{output_extension}}\"\n"
     "      depend_output =\n"
-    "        \"{{root_out_dir}}/{{target_output_name}}"
+    "        \"{{output_dir}}/{{target_output_name}}"
                  "{{output_extension}}.TOC\"\n"
     "      restat = true\n"
     "    }\n"
     "\n"
     "Example\n"
     "\n"
     "  toolchain(\"my_toolchain\") {\n"
     "    # Put these at the top to apply to all tools below.\n"
     "    lib_prefix = \"-l\"\n"
     "    lib_dir_prefix = \"-L\"\n"
@@ skipping 79 matching lines @@
       !ReadString(&block_scope, "lib_dir_switch", tool.get(),
                   &Tool::set_lib_dir_switch, err) ||
       !ReadPattern(&block_scope, "link_output", subst_validator, tool.get(),
                    &Tool::set_link_output, err) ||
       !ReadPattern(&block_scope, "depend_output", subst_validator, tool.get(),
                    &Tool::set_depend_output, err) ||
       !ReadPattern(&block_scope, "runtime_link_output", subst_validator,
                    tool.get(), &Tool::set_runtime_link_output, err) ||
       !ReadString(&block_scope, "output_prefix", tool.get(),
                   &Tool::set_output_prefix, err) ||
+      !ReadPattern(&block_scope, "default_output_dir", subst_validator,
+                   tool.get(), &Tool::set_default_output_dir, err) ||
       !ReadPrecompiledHeaderType(&block_scope, tool.get(), err) ||
       !ReadBool(&block_scope, "restat", tool.get(), &Tool::set_restat, err) ||
       !ReadPattern(&block_scope, "rspfile", subst_validator, tool.get(),
                    &Tool::set_rspfile, err) ||
       !ReadPattern(&block_scope, "rspfile_content", subst_validator, tool.get(),
                    &Tool::set_rspfile_content, err)) {
     return Value();
   }
 
   if (tool_type != Toolchain::TYPE_COPY &&
@@ skipping 134 matching lines @@
     return Value();
 
   Scope::KeyValueMap values;
   block_scope.GetCurrentScopeValues(&values);
   toolchain->args() = values;
 
   return Value();
 }
 
 }  // namespace functions