Add GN help for toolchain commands.

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 "tools/gn/err.h"
 #include "tools/gn/functions.h"
 #include "tools/gn/parse_tree.h"
 #include "tools/gn/scheduler.h"
 #include "tools/gn/scope.h"
 #include "tools/gn/settings.h"
@@ skipping 19 matching lines @@
   *dest = v->string_value();
   return true;
 }
 
 }  // namespace
 
 // toolchain -------------------------------------------------------------------
 
 const char kToolchain[] = "toolchain";
 const char kToolchain_Help[] =
-    "TODO(brettw) write this.";
+    "toolchain: Defines a toolchain.\n"
+    "\n"
+    "  A toolchain is a set of commands and build flags use to compile the\n"

[koz (OOO until 15th September), 2013/09/16 23:05:42]

nit: use -> used

+    "  source code. You can have more than one toolchain in use at once in\n"
+    "  a build.\n"
+    "\n"
+    "  A toolchain specifies the commands to run for various input files\n"

[koz (OOO until 15th September), 2013/09/16 23:05:42]

"input files types" -> "input file types" ?

+    "  types via the \"tool\" call (see \"gn help tool\") and specifies\n"
+    "  arguments to be passed to the toolchain build via the\n"
+    "  \"toolchain_args\" call (see \"gn help toolchain_args\").\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 dependant.\n"
+    "\n"
+    "  You can override this and refer to any other toolchain by explicitly\n"
+    "  labeling the toolchain to use. For example:\n"
+    "    datadeps = [ \"//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 (see \"gn help toolchain_args\").\n"
+    "   3. Loads the destination build file in the context of the\n"
+    "      configuration file in the previous step.\n"
+    "\n"
+    "Example:\n"
+    "  toolchain(\"plugin_toolchain\") {\n"
+    "    tool(\"cc\") {\n"
+    "      command = \"gcc $in\""
+    "    }\n"
+    "\n"
+    "    toolchain_args() {\n"
+    "      is_plugin = true\n"
+    "      is_32bit = true\n"
+    "      is_64bit = false\n"
+    "    }\n"
+    "  }\n";
 
 Value RunToolchain(Scope* scope,
                    const FunctionCallNode* function,
                    const std::vector<Value>& args,
                    BlockNode* block,
                    Err* err) {
   if (!EnsureNotProcessingImport(function, scope, err) ||
       !EnsureNotProcessingBuildConfig(function, scope, err))
     return Value();
 
@@ skipping 29 matching lines @@
     build_settings->item_tree().MarkItemDefinedLocked(build_settings, label,
                                                       err);
   }
   return Value();
 }
 
 // tool ------------------------------------------------------------------------
 
 const char kTool[] = "tool";
 const char kTool_Help[] =
-    "TODO(brettw) write this.";
+    "tool: Specify arguments to a toolchain tool.\n"
+    "\n"
+    "  tool(<command type>) { <command flags> }\n"
+    "\n"
+    "  Used inside a toolchain definition to define a command to run for a\n"
+    "  given file type. See also \"gn help toolchain\".\n"
+    "\n"
+    "Command types:\n"
+    "  The following values may be passed to the tool() function for the type\n"
+    "  of the command:\n"
+    "\n"
+    "  \"cc\", \"cxx\", \"objc\", \"objcxx\", \"asm\", \"alink\", \"solink\",\n"
+    "  \"link\", \"stamp\", \"copy\"\n"
+    "\n"
+    "Command flags:\n"
+    "\n"
+    "  These variables may be specified in the { } block after the tool call.\n"
+    "  They are passed directly to Ninja. See the ninja documentation for how\n"
+    "  they work. Don't forget to backslash-escape $ required by Ninja to\n"
+    "  prevent GN from doing variable expansion.\n"
+    "\n"
+    "  command, depfile, deps, description, pool, restat, rspfile,\n"
+    "  rspfile_content\n"
+    "\n"
+    "Example:\n"
+    "  toolchain(\"my_toolchain\") {\n"
+    "    tool(\"cc\") {\n"
+    "      command = \"gcc \\$in -o \\$out\"\n"
+    "      description = \"GCC \\$in\"\n"
+    "    }\n"
+    "    tool(\"cxx\") {\n"
+    "      command = \"g++ \\$in -o \\$out\"\n"
+    "      description = \"G++ \\$in\"\n"
+    "    }\n"
+    "  }\n";
 
 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, NULL));
@@ skipping 38 matching lines @@
   toolchain->SetTool(tool_type, t);
   return Value();
 }
 
 // toolchain_args --------------------------------------------------------------
 
 extern const char kToolchainArgs[] = "toolchain_args";
 extern const char kToolchainArgs_Help[] =
     "toolchain_args: Set build arguments for toolchain build setup.\n"
     "\n"
+    "  Used inside a toolchain definition to pass arguments to an alternate\n"
+    "  toolchain's invocation of the build.\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. This function allows you to control the arguments passed\n"
-    "  into this alternate invocation of the build.\n"
+    "  toolchain (see \"gn help toolchain\"). The toolchain_args function\n"
+    "  allows you to control the arguments passed into this alternate\n"
+    "  invocation of the build.\n"
     "\n"
     "  Any default system arguments or arguments passed in on the command-\n"
     "  line will also be passed to the alternate invocation unless explicitly\n"
-    "  overriddey by toolchain_args.\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"
     "Example:\n"
     "  toolchain(\"my_weird_toolchain\") {\n"
     "    ...\n"
@@ skipping 37 matching lines @@
     return Value();
 
   Scope::KeyValueMap values;
   block_scope.GetCurrentScopeValues(&values);
   toolchain->args() = values;
 
   return Value();
 }
 
 }  // namespace functions