Convert gn docstrings to C++11 raw strings.

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 284 matching lines @@
 }
 
 }  // namespace
 
 // toolchain -------------------------------------------------------------------
 
 const char kToolchain[] = "toolchain";
 const char kToolchain_HelpShort[] =
     "toolchain: Defines a toolchain.";
 const char kToolchain_Help[] =
-    "toolchain: Defines a toolchain.\n"
-    "\n"
-    "  A toolchain is a set of commands and build flags used to compile the\n"
-    "  source code. You can have more than one toolchain in use at once in\n"
-    "  a build.\n"
-    "\n"
-    "Functions and variables\n"
-    "\n"
-    "  tool()\n"
-    "    The tool() function call specifies the commands commands to run for\n"
-    "    a given step. See \"gn help tool\".\n"
-    "\n"
-    "  toolchain_args\n"
-    "    Overrides for build arguments to pass to the toolchain when invoking\n"
-    "    it. This is a variable of type \"scope\" where the variable names\n"
-    "    correspond to variables in declare_args() blocks.\n"
-    "\n"
-    "    When you specify a target using an alternate toolchain, the master\n"
-    "    build configuration file is re-interpreted in the context of that\n"
-    "    toolchain. toolchain_args allows you to control the arguments\n"
-    "    passed into this alternate invocation of the build.\n"
-    "\n"
-    "    Any default system arguments or arguments passed in via \"gn args\"\n"
-    "    will also be passed to the alternate invocation unless explicitly\n"
-    "    overridden by toolchain_args.\n"
-    "\n"
-    "    The toolchain_args will be ignored when the toolchain being defined\n"
-    "    is the default. In this case, it's expected you want the default\n"
-    "    argument values.\n"
-    "\n"
-    "    See also \"gn help buildargs\" for an overview of these arguments.\n"
-    "\n"
-    "  deps\n"
-    "    Dependencies of this toolchain. These dependencies will be resolved\n"
-    "    before any target in the toolchain is compiled. To avoid circular\n"
-    "    dependencies these must be targets defined in another toolchain.\n"
-    "\n"
-    "    This is expressed as a list of targets, and generally these targets\n"
-    "    will always specify a toolchain:\n"
-    "      deps = [ \"//foo/bar:baz(//build/toolchain:bootstrap)\" ]\n"
-    "\n"
-    "    This concept is somewhat inefficient to express in Ninja (it\n"
-    "    requires a lot of duplicate of rules) so should only be used when\n"
-    "    absolutely necessary.\n"
-    "\n"
-    "Invoking targets in toolchains:\n"
-    "\n"
-    "  By default, when a target depends on another, there is an implicit\n"
-    "  toolchain label that is inherited, so the dependee has the same one\n"
-    "  as the dependent.\n"
-    "\n"
-    "  You can override this and refer to any other toolchain by explicitly\n"
-    "  labeling the toolchain to use. For example:\n"
-    "    data_deps = [ \"//plugins:mine(//toolchains:plugin_toolchain)\" ]\n"
-    "  The string \"//build/toolchains:plugin_toolchain\" is a label that\n"
-    "  identifies the toolchain declaration for compiling the sources.\n"
-    "\n"
-    "  To load a file in an alternate toolchain, GN does the following:\n"
-    "\n"
-    "   1. Loads the file with the toolchain definition in it (as determined\n"
-    "      by the toolchain label).\n"
-    "   2. Re-runs the master build configuration file, applying the\n"
-    "      arguments specified by the toolchain_args section of the toolchain\n"
-    "      definition.\n"
-    "   3. Loads the destination build file in the context of the\n"
-    "      configuration file in the previous step.\n"
-    "\n"
-    "Example\n"
-    "\n"
-    "  toolchain(\"plugin_toolchain\") {\n"
-    "    tool(\"cc\") {\n"
-    "      command = \"gcc {{source}}\"\n"
-    "      ...\n"
-    "    }\n"
-    "\n"
-    "    toolchain_args = {\n"
-    "      is_plugin = true\n"
-    "      is_32bit = true\n"
-    "      is_64bit = false\n"
-    "    }\n"
-    "  }\n";
+    R"*(toolchain: Defines a toolchain.
+
+  A toolchain is a set of commands and build flags used to compile the source
+  code. You can have more than one toolchain in use at once in a build.
+
+Functions and variables
+
+  tool()
+    The tool() function call specifies the commands commands to run for a given
+    step. See "gn help tool".
+
+  toolchain_args
+    Overrides for build arguments to pass to the toolchain when invoking it.
+    This is a variable of type "scope" where the variable names correspond to
+    variables in declare_args() blocks.
+
+    When you specify a target using an alternate toolchain, the master build
+    configuration file is re-interpreted in the context of that toolchain.
+    toolchain_args allows you to control the arguments passed into this
+    alternate invocation of the build.
+
+    Any default system arguments or arguments passed in via "gn args" will also
+    be passed to the alternate invocation unless explicitly overridden by
+    toolchain_args.
+
+    The toolchain_args will be ignored when the toolchain being defined is the
+    default. In this case, it's expected you want the default argument values.
+
+    See also "gn help buildargs" for an overview of these arguments.
+
+  deps
+    Dependencies of this toolchain. These dependencies will be resolved before
+    any target in the toolchain is compiled. To avoid circular dependencies
+    these must be targets defined in another toolchain.
+
+    This is expressed as a list of targets, and generally these targets will
+    always specify a toolchain:
+      deps = [ "//foo/bar:baz(//build/toolchain:bootstrap)" ]
+
+    This concept is somewhat inefficient to express in Ninja (it requires a lot
+    of duplicate of rules) so should only be used when absolutely necessary.
+
+Invoking targets in toolchains
+
+  By default, when a target depends on another, there is an implicit toolchain
+  label that is inherited, so the dependee has the same one as the dependent.
+
+  You can override this and refer to any other toolchain by explicitly
+  labeling the toolchain to use. For example:
+    data_deps = [ "//plugins:mine(//toolchains:plugin_toolchain)" ]
+  The string "//build/toolchains:plugin_toolchain" is a label that identifies
+  the toolchain declaration for compiling the sources.
+
+  To load a file in an alternate toolchain, GN does the following:
+
+   1. Loads the file with the toolchain definition in it (as determined by the
+      toolchain label).
+   2. Re-runs the master build configuration file, applying the arguments
+      specified by the toolchain_args section of the toolchain definition.
+   3. Loads the destination build file in the context of the configuration file
+      in the previous step.
+
+Example
+
+  toolchain("plugin_toolchain") {
+    tool("cc") {
+      command = "gcc {{source}}"
+      ...
+    }
+
+    toolchain_args = {
+      is_plugin = true
+      is_32bit = true
+      is_64bit = false
+    }
+  };
+)*";
 
 Value RunToolchain(Scope* scope,
                    const FunctionCallNode* function,
                    const std::vector<Value>& args,
                    BlockNode* block,
                    Err* err) {
   NonNestableBlock non_nestable(scope, function, "toolchain");
   if (!non_nestable.Enter(err))
     return Value();
 
@@ skipping 56 matching lines @@
   collector->push_back(toolchain.release());
   return Value();
 }
 
 // tool ------------------------------------------------------------------------
 
 const char kTool[] = "tool";
 const char kTool_HelpShort[] =
     "tool: Specify arguments to a toolchain tool.";
 const char kTool_Help[] =
-    "tool: Specify arguments to a toolchain tool.\n"
-    "\n"
-    "Usage:\n"
-    "\n"
-    "  tool(<tool type>) {\n"
-    "    <tool variables...>\n"
-    "  }\n"
-    "\n"
-    "Tool types\n"
-    "\n"
-    "    Compiler tools:\n"
-    "      \"cc\": C compiler\n"
-    "      \"cxx\": C++ compiler\n"
-    "      \"objc\": Objective C compiler\n"
-    "      \"objcxx\": Objective C++ compiler\n"
-    "      \"rc\": Resource compiler (Windows .rc files)\n"
-    "      \"asm\": Assembler\n"
-    "\n"
-    "    Linker tools:\n"
-    "      \"alink\": Linker for static libraries (archives)\n"
-    "      \"solink\": Linker for shared libraries\n"
-    "      \"link\": Linker for executables\n"
-    "\n"
-    "    Other tools:\n"
-    "      \"stamp\": Tool for creating stamp files\n"
-    "      \"copy\": Tool to copy files.\n"
-    "\n"
-    "    Platform specific tools:\n"
-    "      \"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 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"
-    "        Valid for: compiler tools (when depfile is specified)\n"
-    "\n"
-    "        Format for the deps outputs. This is either \"gcc\" or \"msvc\".\n"
-    "        See the ninja documentation for \"deps\" for more information.\n"
-    "\n"
-    "        Example: depsformat = \"gcc\"\n"
-    "\n"
-    "    description  [string with substitutions, optional]\n"
-    "        Valid for: all tools\n"
-    "\n"
-    "        What to print when the command is run.\n"
-    "\n"
-    "        Example: description = \"Compiling {{source}}\"\n"
-    "\n"
-    "    lib_switch  [string, optional, link tools only]\n"
-    "    lib_dir_switch  [string, optional, link tools only]\n"
-    "        Valid for: Linker tools except \"alink\"\n"
-    "\n"
-    "        These strings will be prepended to the libraries and library\n"
-    "        search directories, respectively, because linkers differ on how\n"
-    "        specify them. If you specified:\n"
-    "          lib_switch = \"-l\"\n"
-    "          lib_dir_switch = \"-L\"\n"
-    "        then the \"{{libs}}\" expansion for [ \"freetype\", \"expat\"]\n"
-    "        would be \"-lfreetype -lexpat\".\n"
-    "\n"
-    "    outputs  [list of strings with substitutions]\n"
-    "        Valid for: Linker and compiler tools (required)\n"
-    "\n"
-    "        An array of names for the output files the tool produces. These\n"
-    "        are relative to the build output directory. There must always be\n"
-    "        at least one output file. There can be more than one output (a\n"
-    "        linker might produce a library and an import library, for\n"
-    "        example).\n"
-    "\n"
-    "        This array just declares to GN what files the tool will\n"
-    "        produce. It is your responsibility to specify the tool command\n"
-    "        that actually produces these files.\n"
-    "\n"
-    "        If you specify more than one output for shared library links,\n"
-    "        you should consider setting link_output, depend_output, and\n"
-    "        runtime_outputs.\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 {{target_output_name}}, {{output_extension}} and\n"
-    "        {{output_dir}} allows the target to override these values.\n"
-    "          outputs = [\n"
-    "            \"{{output_dir}}/{{target_output_name}}"
-                     "{{output_extension}}\",\n"
-    "            \"{{output_dir}}/{{target_output_name}}.lib\",\n"
-    "          ]\n"
-    "\n"
-    "    pool [label, optional]\n"
-    "\n"
-    "        Label of the pool to use for the tool. Pools are used to limit\n"
-    "        the number of tasks that can execute concurrently during the\n"
-    "        build.\n"
-    "\n"
-    "        See also \"gn help pool\".\n"
-    "\n"
-    "    link_output  [string with substitutions]\n"
-    "    depend_output  [string with substitutions]\n"
-    "        Valid for: \"solink\" only (optional)\n"
-    "\n"
-    "        These two 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.\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"
-    "\n"
-    "        Prefix to use for the output name. Defaults to empty. This\n"
-    "        prefix will be prepended to the name of the target (or the\n"
-    "        output_name if one is manually specified for it) if the prefix\n"
-    "        is not already there. The result will show up in the\n"
-    "        {{output_name}} substitution pattern.\n"
-    "\n"
-    "        Individual targets can opt-out of the output prefix by setting:\n"
-    "          output_prefix_override = true\n"
-    "        (see \"gn help output_prefix_override\").\n"
-    "\n"
-    "        This is typically used to prepend \"lib\" to libraries on\n"
-    "        Posix systems:\n"
-    "          output_prefix = \"lib\"\n"
-    "\n"
-    "    precompiled_header_type  [string]\n"
-    "        Valid for: \"cc\", \"cxx\", \"objc\", \"objcxx\"\n"
-    "\n"
-    "        Type of precompiled headers. If undefined or the empty string,\n"
-    "        precompiled headers will not be used for this tool. Otherwise\n"
-    "        use \"gcc\" or \"msvc\".\n"
-    "\n"
-    "        For precompiled headers to be used for a given target, the\n"
-    "        target (or a config applied to it) must also specify a\n"
-    "        \"precompiled_header\" and, for \"msvc\"-style headers, a\n"
-    "        \"precompiled_source\" value. If the type is \"gcc\", then both\n"
-    "        \"precompiled_header\" and \"precompiled_source\" must resolve\n"
-    "        to the same file, despite the different formats required for each."
-    "\n"
-    "        See \"gn help precompiled_header\" for more.\n"
-    "\n"
-    "    restat  [boolean]\n"
-    "        Valid for: all tools (optional, defaults to false)\n"
-    "\n"
-    "        Requests that Ninja check the file timestamp after this tool has\n"
-    "        run to determine if anything changed. Set this if your tool has\n"
-    "        the ability to skip writing output if the output file has not\n"
-    "        changed.\n"
-    "\n"
-    "        Normally, Ninja will assume that when a tool runs the output\n"
-    "        be new and downstream dependents must be rebuild. When this is\n"
-    "        set to trye, Ninja can skip rebuilding downstream dependents for\n"
-    "        input changes that don't actually affect the output.\n"
-    "\n"
-    "        Example:\n"
-    "          restat = true\n"
-    "\n"
-    "    rspfile  [string with substitutions]\n"
-    "        Valid for: all tools (optional)\n"
-    "\n"
-    "        Name of the response file. If empty, no response file will be\n"
-    "        used. See \"rspfile_content\".\n"
-    "\n"
-    "    rspfile_content  [string with substitutions]\n"
-    "        Valid for: all tools (required when \"rspfile\" is specified)\n"
-    "\n"
-    "        The contents to be written to the response file. This may\n"
-    "        include all or part of the command to send to the tool which\n"
-    "        allows you to get around OS command-line length limits.\n"
-    "\n"
-    "        This example adds the inputs and libraries to a response file,\n"
-    "        but passes the linker flags directly on the command line:\n"
-    "          tool(\"link\") {\n"
-    "            command = \"link -o {{output}} {{ldflags}} @{{output}}.rsp\"\n"
-    "            rspfile = \"{{output}}.rsp\"\n"
-    "            rspfile_content = \"{{inputs}} {{solibs}} {{libs}}\"\n"
-    "          }\n"
-    "\n"
-    "    runtime_outputs  [string list with substitutions]\n"
-    "        Valid for: linker tools\n"
-    "\n"
-    "        If specified, this list is the subset of the outputs that should\n"
-    "        be added to runtime deps (see \"gn help runtime_deps\"). By\n"
-    "        default (if runtime_outputs is empty or unspecified), it will be\n"
-    "        the link_output.\n"
-    "\n"
-    "Expansions for tool variables\n"
-    "\n"
-    "  All paths are relative to the root build directory, which is the\n"
-    "  current directory for running all tools. These expansions are\n"
-    "  available to all tools:\n"
-    "\n"
-    "    {{label}}\n"
-    "        The label of the current target. This is typically used in the\n"
-    "        \"description\" field for link tools. The toolchain will be\n"
-    "        omitted from the label for targets in the default toolchain, and\n"
-    "        will be included for targets in other toolchains.\n"
-    "\n"
-    "    {{label_name}}\n"
-    "        The short name of the label of the target. This is the part\n"
-    "        after the colon. For \"//foo/bar:baz\" this will be \"baz\".\n"
-    "        Unlike {{target_output_name}}, this is not affected by the\n"
-    "        \"output_prefix\" in the tool or the \"output_name\" set\n"
-    "        on the target.\n"
-    "\n"
-    "    {{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. 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"
-    "  Compiler tools have the notion of a single input and a single output,\n"
-    "  along with a set of compiler-specific flags. The following expansions\n"
-    "  are available:\n"
-    "\n"
-    "    {{asmflags}}\n"
-    "    {{cflags}}\n"
-    "    {{cflags_c}}\n"
-    "    {{cflags_cc}}\n"
-    "    {{cflags_objc}}\n"
-    "    {{cflags_objcc}}\n"
-    "    {{defines}}\n"
-    "    {{include_dirs}}\n"
-    "        Strings correspond that to the processed flags/defines/include\n"
-    "        directories specified for the target.\n"
-    "        Example: \"--enable-foo --enable-bar\"\n"
-    "\n"
-    "        Defines will be prefixed by \"-D\" and include directories will\n"
-    "        be prefixed by \"-I\" (these work with Posix tools as well as\n"
-    "        Microsoft ones).\n"
-    "\n"
-    "    {{source}}\n"
-    "        The relative path and name of the current input file.\n"
-    "        Example: \"../../base/my_file.cc\"\n"
-    "\n"
-    "    {{source_file_part}}\n"
-    "        The file part of the source including the extension (with no\n"
-    "        directory information).\n"
-    "        Example: \"foo.cc\"\n"
-    "\n"
-    "    {{source_name_part}}\n"
-    "        The filename part of the source file with no directory or\n"
-    "        extension.\n"
-    "        Example: \"foo\"\n"
-    "\n"
-    "    {{source_gen_dir}}\n"
-    "    {{source_out_dir}}\n"
-    "        The directory in the generated file and output directories,\n"
-    "        respectively, for the current input file. If the source file\n"
-    "        is in the same directory as the target is declared in, they will\n"
-    "        will be the same as the \"target\" versions above.\n"
-    "        Example: \"gen/base/test\"\n"
-    "\n"
-    "  Linker tools have multiple inputs and (potentially) multiple outputs\n"
-    "  The static library tool (\"alink\") is not considered a linker tool.\n"
-    "  The following expansions are available:\n"
-    "\n"
-    "    {{inputs}}\n"
-    "    {{inputs_newline}}\n"
-    "        Expands to the inputs to the link step. This will be a list of\n"
-    "        object files and static libraries.\n"
-    "        Example: \"obj/foo.o obj/bar.o obj/somelibrary.a\"\n"
-    "\n"
-    "        The \"_newline\" version will separate the input files with\n"
-    "        newlines instead of spaces. This is useful in response files:\n"
-    "        some linkers can take a \"-filelist\" flag which expects newline\n"
-    "        separated files, and some Microsoft tools have a fixed-sized\n"
-    "        buffer for parsing each line of a response file.\n"
-    "\n"
-    "    {{ldflags}}\n"
-    "        Expands to the processed set of ldflags and library search paths\n"
-    "        specified for the target.\n"
-    "        Example: \"-m64 -fPIC -pthread -L/usr/local/mylib\"\n"
-    "\n"
-    "    {{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"
-    "        variable separate from the \"depend_output\").\n"
-    "\n"
-    "        These should generally be treated the same as libs by your tool.\n"
-    "        Example: \"libfoo.so libbar.so\"\n"
-    "\n"
-    "  The static library (\"alink\") tool allows {{arflags}} plus the common\n"
-    "  tool substitutions.\n"
-    "\n"
-    "  The copy tool allows the common compiler/linker substitutions, plus\n"
-    "  {{source}} which is the source of the copy. The stamp tool allows\n"
-    "  only the common tool substitutions.\n"
-    "\n"
-    "  The copy_bundle_data and compile_xcassets tools only allows the common\n"
-    "  tool substitutions. Both tools are required to create iOS/OS X bundles\n"
-    "  and need only be defined on those platforms.\n"
-    "\n"
-    "  The copy_bundle_data tool will be called with one source and needs to\n"
-    "  copy (optionally optimizing the data representation) to its output. It\n"
-    "  may be called with a directory as input and it needs to be recursively\n"
-    "  copied.\n"
-    "\n"
-    "  The compile_xcassets tool will be called with one or more source (each\n"
-    "  an asset catalog) that needs to be compiled to a single output. The\n"
-    "  following substitutions are avaiable:\n"
-    "\n"
-    "    {{inputs}}\n"
-    "        Expands to the list of .xcassets to use as input to compile the\n"
-    "        asset catalog.\n"
-    "\n"
-    "    {{bundle_product_type}}\n"
-    "        Expands to the product_type of the bundle that will contain the\n"
-    "        compiled asset catalog. Usually corresponds to the product_type\n"
-    "        property of the corresponding create_bundle target.\n"
-    "\n"
-    "Separate linking and dependencies for shared libraries\n"
-    "\n"
-    "  Shared libraries are special in that not all changes to them require\n"
-    "  that dependent targets be re-linked. If the shared library is changed\n"
-    "  but no imports or exports are different, dependent code needn't be\n"
-    "  relinked, which can speed up the build.\n"
-    "\n"
-    "  If your link step can output a list of exports from a shared library\n"
-    "  and writes the file only if the new one is different, the timestamp of\n"
-    "  this file can be used for triggering re-links, while the actual shared\n"
-    "  library would be used for linking.\n"
-    "\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"
-    "        \"{{output_dir}}/{{target_output_name}}{{output_extension}}\",\n"
-    "        \"{{output_dir}}/{{target_output_name}}"
-                 "{{output_extension}}.TOC\",\n"
-    "      ]\n"
-    "      link_output =\n"
-    "        \"{{output_dir}}/{{target_output_name}}{{output_extension}}\"\n"
-    "      depend_output =\n"
-    "        \"{{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"
-    "\n"
-    "    tool(\"cc\") {\n"
-    "      command = \"gcc {{source}} -o {{output}}\"\n"
-    "      outputs = [ \"{{source_out_dir}}/{{source_name_part}}.o\" ]\n"
-    "      description = \"GCC {{source}}\"\n"
-    "    }\n"
-    "    tool(\"cxx\") {\n"
-    "      command = \"g++ {{source}} -o {{output}}\"\n"
-    "      outputs = [ \"{{source_out_dir}}/{{source_name_part}}.o\" ]\n"
-    "      description = \"G++ {{source}}\"\n"
-    "    }\n"
-    "  }\n";
+    R"(tool: Specify arguments to a toolchain tool.
+
+Usage
+
+  tool(<tool type>) {
+    <tool variables...>
+  }
+
+Tool types
+
+    Compiler tools:
+      "cc": C compiler
+      "cxx": C++ compiler
+      "objc": Objective C compiler
+      "objcxx": Objective C++ compiler
+      "rc": Resource compiler (Windows .rc files)
+      "asm": Assembler
+
+    Linker tools:
+      "alink": Linker for static libraries (archives)
+      "solink": Linker for shared libraries
+      "link": Linker for executables
+
+    Other tools:
+      "stamp": Tool for creating stamp files
+      "copy": Tool to copy files.
+
+    Platform specific tools:
+      "copy_bundle_data": [iOS, OS X] Tool to copy files in a bundle.
+      "compile_xcassets": [iOS, OS X] Tool to compile asset catalogs.
+
+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 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]
+        Valid for: compiler tools (when depfile is specified)
+
+        Format for the deps outputs. This is either "gcc" or "msvc". See the
+        ninja documentation for "deps" for more information.
+
+        Example: depsformat = "gcc"
+
+    description  [string with substitutions, optional]
+        Valid for: all tools
+
+        What to print when the command is run.
+
+        Example: description = "Compiling {{source}}"
+
+    lib_switch  [string, optional, link tools only]
+    lib_dir_switch  [string, optional, link tools only]
+        Valid for: Linker tools except "alink"
+
+        These strings will be prepended to the libraries and library search
+        directories, respectively, because linkers differ on how specify them.
+        If you specified:
+          lib_switch = "-l"
+          lib_dir_switch = "-L"
+        then the "{{libs}}" expansion for [ "freetype", "expat"] would be
+        "-lfreetype -lexpat".
+
+    outputs  [list of strings with substitutions]
+        Valid for: Linker and compiler tools (required)
+
+        An array of names for the output files the tool produces. These are
+        relative to the build output directory. There must always be at least
+        one output file. There can be more than one output (a linker might
+        produce a library and an import library, for example).
+
+        This array just declares to GN what files the tool will produce. It is
+        your responsibility to specify the tool command that actually produces
+        these files.
+
+        If you specify more than one output for shared library links, you
+        should consider setting link_output, depend_output, and
+        runtime_outputs.
+
+        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
+        {{target_output_name}}, {{output_extension}} and {{output_dir}} allows
+        the target to override these values.
+          outputs = [
+            "{{output_dir}}/{{target_output_name}}"
+                "{{output_extension}}",
+            "{{output_dir}}/{{target_output_name}}.lib",
+          ]
+
+    pool [label, optional]
+
+        Label of the pool to use for the tool. Pools are used to limit the
+        number of tasks that can execute concurrently during the build.
+
+        See also "gn help pool".
+
+    link_output  [string with substitutions]
+    depend_output  [string with substitutions]
+        Valid for: "solink" only (optional)
+
+        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 all. 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 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)
+
+        Prefix to use for the output name. Defaults to empty. This prefix will
+        be prepended to the name of the target (or the output_name if one is
+        manually specified for it) if the prefix is not already there. The
+        result will show up in the {{output_name}} substitution pattern.
+
+        Individual targets can opt-out of the output prefix by setting:
+          output_prefix_override = true
+        (see "gn help output_prefix_override").
+
+        This is typically used to prepend "lib" to libraries on
+        Posix systems:
+          output_prefix = "lib"
+
+    precompiled_header_type  [string]
+        Valid for: "cc", "cxx", "objc", "objcxx"
+
+        Type of precompiled headers. If undefined or the empty string,
+        precompiled headers will not be used for this tool. Otherwise use "gcc"
+        or "msvc".
+
+        For precompiled headers to be used for a given target, the target (or a
+        config applied to it) must also specify a "precompiled_header" and, for
+        "msvc"-style headers, a "precompiled_source" value. If the type is
+        "gcc", then both "precompiled_header" and "precompiled_source" must
+        resolve to the same file, despite the different formats required for
+        each."
+
+        See "gn help precompiled_header" for more.
+
+    restat  [boolean]
+        Valid for: all tools (optional, defaults to false)
+
+        Requests that Ninja check the file timestamp after this tool has run to
+        determine if anything changed. Set this if your tool has the ability to
+        skip writing output if the output file has not changed.
+
+        Normally, Ninja will assume that when a tool runs the output be new and
+        downstream dependents must be rebuild. When this is set to trye, Ninja
+        can skip rebuilding downstream dependents for input changes that don't
+        actually affect the output.
+
+        Example:
+          restat = true
+
+    rspfile  [string with substitutions]
+        Valid for: all tools (optional)
+
+        Name of the response file. If empty, no response file will be
+        used. See "rspfile_content".
+
+    rspfile_content  [string with substitutions]
+        Valid for: all tools (required when "rspfile" is specified)
+
+        The contents to be written to the response file. This may include all
+        or part of the command to send to the tool which allows you to get
+        around OS command-line length limits.
+
+        This example adds the inputs and libraries to a response file, but
+        passes the linker flags directly on the command line:
+          tool("link") {
+            command = "link -o {{output}} {{ldflags}} @{{output}}.rsp"
+            rspfile = "{{output}}.rsp"
+            rspfile_content = "{{inputs}} {{solibs}} {{libs}}"
+          }
+
+    runtime_outputs  [string list with substitutions]
+        Valid for: linker tools
+
+        If specified, this list is the subset of the outputs that should be
+        added to runtime deps (see "gn help runtime_deps"). By default (if
+        runtime_outputs is empty or unspecified), it will be the link_output.
+
+Expansions for tool variables
+
+  All paths are relative to the root build directory, which is the current
+  directory for running all tools. These expansions are available to all tools:
+
+    {{label}}
+        The label of the current target. This is typically used in the
+        "description" field for link tools. The toolchain will be omitted from
+        the label for targets in the default toolchain, and will be included
+        for targets in other toolchains.
+
+    {{label_name}}
+        The short name of the label of the target. This is the part after the
+        colon. For "//foo/bar:baz" this will be "baz". Unlike
+        {{target_output_name}}, this is not affected by the "output_prefix" in
+        the tool or the "output_name" set on the target.
+
+    {{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. 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".
+
+)"  // String break to prevent overflowing the 16K max VC string length.
+R"(  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"
+
+        Defines will be prefixed by "-D" and include directories will be
+        prefixed by "-I" (these work with Posix tools as well as Microsoft
+        ones).
+
+    {{source}}
+        The relative path and name of the current input file.
+        Example: "../../base/my_file.cc"
+
+    {{source_file_part}}
+        The file part of the source including the extension (with no directory
+        information).
+        Example: "foo.cc"
+
+    {{source_name_part}}
+        The filename part of the source file with no directory or extension.
+        Example: "foo"
+
+    {{source_gen_dir}}
+    {{source_out_dir}}
+        The directory in the generated file and output directories,
+        respectively, for the current input file. If the source file is in the
+        same directory as the target is declared in, they will will be the same
+        as the "target" versions above. Example: "gen/base/test"
+
+  Linker tools have multiple inputs and (potentially) multiple outputs The
+  static library tool ("alink") is not considered a linker tool. The following
+  expansions are available:
+
+    {{inputs}}
+    {{inputs_newline}}
+        Expands to the inputs to the link step. This will be a list of object
+        files and static libraries.
+        Example: "obj/foo.o obj/bar.o obj/somelibrary.a"
+
+        The "_newline" version will separate the input files with newlines
+        instead of spaces. This is useful in response files: some linkers can
+        take a "-filelist" flag which expects newline separated files, and some
+        Microsoft tools have a fixed-sized buffer for parsing each line of a
+        response file.
+
+    {{ldflags}}
+        Expands to the processed set of ldflags and library search paths
+        specified for the target.
+        Example: "-m64 -fPIC -pthread -L/usr/local/mylib"
+
+    {{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" variable separate from
+        the "depend_output").
+
+        These should generally be treated the same as libs by your tool.
+
+        Example: "libfoo.so libbar.so"
+
+)"  // String break to prevent overflowing the 16K max VC string length.
+R"(  The static library ("alink") tool allows {{arflags}} plus the common tool
+  substitutions.
+
+  The copy tool allows the common compiler/linker substitutions, plus
+  {{source}} which is the source of the copy. The stamp tool allows only the
+  common tool substitutions.
+
+  The copy_bundle_data and compile_xcassets tools only allows the common tool
+  substitutions. Both tools are required to create iOS/OS X bundles and need
+  only be defined on those platforms.
+
+  The copy_bundle_data tool will be called with one source and needs to copy
+  (optionally optimizing the data representation) to its output. It may be
+  called with a directory as input and it needs to be recursively copied.
+
+  The compile_xcassets tool will be called with one or more source (each an
+  asset catalog) that needs to be compiled to a single output. The following
+  substitutions are avaiable:
+
+    {{inputs}}
+        Expands to the list of .xcassets to use as input to compile the asset
+        catalog.
+
+    {{bundle_product_type}}
+        Expands to the product_type of the bundle that will contain the
+        compiled asset catalog. Usually corresponds to the product_type
+        property of the corresponding create_bundle target.
+
+Separate linking and dependencies for shared libraries
+
+  Shared libraries are special in that not all changes to them require that
+  dependent targets be re-linked. If the shared library is changed but no
+  imports or exports are different, dependent code needn't be relinked, which
+  can speed up the build.
+
+  If your link step can output a list of exports from a shared library and
+  writes the file only if the new one is different, the timestamp of this file
+  can be used for triggering re-links, while the actual shared library would be
+  used for linking.
+
+  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 = [
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}",
+        "{{output_dir}}/{{target_output_name}}"
+            "{{output_extension}}.TOC",
+      ]
+      link_output =
+        "{{output_dir}}/{{target_output_name}}{{output_extension}}"
+      depend_output =
+        "{{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.
+    lib_prefix = "-l"
+    lib_dir_prefix = "-L"
+
+    tool("cc") {
+      command = "gcc {{source}} -o {{output}}"
+      outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
+      description = "GCC {{source}}"
+    }
+    tool("cxx") {
+      command = "g++ {{source}} -o {{output}}"
+      outputs = [ "{{source_out_dir}}/{{source_name_part}}.o" ]
+      description = "G++ {{source}}"
+    }
+  };
+)";
 
 Value RunTool(Scope* scope,
               const FunctionCallNode* function,
               const std::vector<Value>& args,
               BlockNode* block,
               Err* err) {
   // Find the toolchain definition we're executing inside of. The toolchain
   // function will set a property pointing to it that we'll pick up.
   Toolchain* toolchain = reinterpret_cast<Toolchain*>(
       scope->GetProperty(&kToolchainPropertyKey, nullptr));
@@ skipping 112 matching lines @@
 
   // Make sure there weren't any vars set in this tool that were unused.
   if (!block_scope.CheckForUnusedVars(err))
     return Value();
 
   toolchain->SetTool(tool_type, std::move(tool));
   return Value();
 }
 
 }  // namespace functions