Add documentation for GN's GYP generation.

tools/gn/command_gyp.cc

Index: tools/gn/command_gyp.cc
diff --git a/tools/gn/command_gyp.cc b/tools/gn/command_gyp.cc
index 4d752000aee2f173b655c063c3784fbf18401649..9daf441878daf38ebea30ea049b4c458d0a34147 100644
--- a/tools/gn/command_gyp.cc
+++ b/tools/gn/command_gyp.cc
@@ -270,7 +270,60 @@ 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();