Add documentation for GN's GYP generation.

tools/gn/command_gyp.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 <iostream>
 #include <map>
 #include <utility>
 #include <vector>
 
 #include "base/command_line.h"
@@ skipping 252 matching lines @@
 }
 
 }  // namespace
 
 // Suppress output on success.
 const char kSwitchQuiet[] = "q";
 
 const char kGyp[] = "gyp";
 const char kGyp_HelpShort[] =
     "gyp: Make GYP files from GN.";
-const char kGyp_Help[] = "Doooooom.\n";
+const char kGyp_Help[] =
+    "gyp: Make GYP files from GN.\n"
+    "\n"
+    "  This command will generate GYP files from GN sources. You can then run\n"
+    "  GYP over the result to produce a build. Native GYP targets can depend\n"
+    "  on any GN target except source sets. GN targets can depend on native\n"
+    "  GYP targets, but all/direct dependent settings will NOT be pushed\n"
+    "  across the boundary.\n"
+    "\n"
+    "  To make this work you first need to manually run GN, then GYP, then\n"
+    "  do the build. Because GN doesn't generate the final .ninja files,\n"
+    "  there will be no rules to regenerate the .ninja files if the inputs\n"
+    "  change, so you will have to manually repeat these steps each time\n"
+    "  something changes:\n"
+    "\n"
+    "    out/Debug/gn gyp\n"
+    "    python build/gyp_chromiunm\n"
+    "    ninja -C out/Debug gn\n"

[jamesr, 2013/10/22 21:54:49]

did you mean

ninja -C out/gn foo_target

? why would you need to recompile gn after regenerating project files?

+    "\n"
+    "  Two variables are used to control how a target relates to GYP:\n"
+    "\n"
+    "  - \"external != true\" and \"gyp_file\" is set: This target will be\n"
+    "    written to the named GYP file.\n"

[jamesr, 2013/10/22 21:54:49]

probably worth calling out that the target will be written to the named gyp file
in the source tree, not the outdir (as i initially assumed)

+    "\n"
+    "  - \"external == true\" and \"gyp_file\" is set: The target will not\n"
+    "    be written to a GYP file. But other targets being written to GYP\n"
+    "    files can depend on it, and they will reference the given GYP file\n"
+    "    name for GYP to use. This allows you to specify how GN->GYP\n"
+    "    dependencies and named, and provides a place to manually set the\n"
+    "    dependent configs from GYP to GN.\n"
+    "\n"
+    "  - \"gyp_file\" is unset: Like the previous case, but if a GN target is\n"
+    "    being written to a GYP file that depends on this one, the default\n"
+    "    GYP file name will be assumed. The default name will match the name\n"
+    "    of the current directory, so \"//foo/bar:baz\" would be\n"
+    "    \"<(DEPTH)/foo/bar/bar.gyp:baz\".\n"
+    "\n"
+    "Example:\n"
+    "  # This target is assumed to be in the GYP build in the file\n"
+    "  # \"foo/foo.gyp\". This declaration tells GN where to find the GYP\n"
+    "  # equivalent, and gives it some direct dependent settings that targets\n"
+    "  # depending on it should receive (since these don't flow from GYP to\n"
+    "  # GN-generated targets).\n"
+    "  shared_library(\"gyp_target\") {\n"
+    "    gyp_file = \"//foo/foo.gyp\"\n"
+    "    external = true\n"
+    "    direct_dependen_configs = [ \":gyp_target_config\" ]\n"
+    "  }\n"
+    "\n"
+    "  executable(\"my_app\") {\n"
+    "    deps = [ \":gyp_target\" ]\n"
+    "    gyp_file = \"//foo/myapp.gyp\"\n"
+    "    sources = ...\n"
+    "  }\n";
 
 int RunGyp(const std::vector<std::string>& args) {
   const CommandLine* cmdline = CommandLine::ForCurrentProcess();
 
   base::TimeTicks begin_time = base::TimeTicks::Now();
 
   // Deliberately leaked to avoid expensive process teardown.
   Setup* setup_debug = new Setup;
   if (!setup_debug->DoSetup())
     return 1;
@@ skipping 41 matching lines @@
         + " GN files in " +
         base::IntToString((end_time - begin_time).InMilliseconds()) + "ms\n";
 
     OutputString(stats);
   }
 
   return 0;
 }
 
 }  // namespace commands