Add GN help for toolchain commands.

BUG=288991
R=koz@chromium.org

Review URL: https://codereview.chromium.org/23970005

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@223470 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 87 insertions, 5 deletions

diff --git a/tools/gn/function_toolchain.cc b/tools/gn/function_toolchain.cc
index fac5492..040c670 100644
--- a/tools/gn/function_toolchain.cc
+++ b/tools/gn/function_toolchain.cc
@@ -37,7 +37,51 @@ bool ReadString(Scope& scope, const char* var, std::string* dest, Err* err) {
 
 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 used to compile the\n"
+    "  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 file\n"
+    "  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,
@@ -87,7 +131,41 @@ Value RunToolchain(Scope* scope,
 
 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,
@@ -146,14 +224,18 @@ 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"