tools/gn/command_help.cc

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #include <algorithm>
   6 #include <iostream>
   7
   8 #include "base/command_line.h"
   9 #include "tools/gn/args.h"
  10 #include "tools/gn/commands.h"
  11 #include "tools/gn/err.h"
  12 #include "tools/gn/functions.h"
  13 #include "tools/gn/input_conversion.h"
  14 #include "tools/gn/label_pattern.h"
  15 #include "tools/gn/parser.h"
  16 #include "tools/gn/runtime_deps.h"
  17 #include "tools/gn/setup.h"
  18 #include "tools/gn/standard_out.h"
  19 #include "tools/gn/substitution_writer.h"
  20 #include "tools/gn/switches.h"
  21 #include "tools/gn/variables.h"
  22
  23 namespace commands {
  24
  25 namespace {
  26
  27 void PrintToplevelHelp() {
  28   OutputString("Commands (type \"gn help <command>\" for more details):\n");
  29   for (const auto& cmd : commands::GetCommands())
  30     PrintShortHelp(cmd.second.help_short);
  31
  32   // Target declarations.
  33   OutputString("\nTarget declarations (type \"gn help <function>\" for more "
  34                "details):\n");
  35   for (const auto& func : functions::GetFunctions()) {
  36     if (func.second.is_target)
  37       PrintShortHelp(func.second.help_short);
  38   }
  39
  40   // Functions.
  41   OutputString("\nBuildfile functions (type \"gn help <function>\" for more "
  42                "details):\n");
  43   for (const auto& func : functions::GetFunctions()) {
  44     if (!func.second.is_target)
  45       PrintShortHelp(func.second.help_short);
  46   }
  47
  48   // Built-in variables.
  49   OutputString("\nBuilt-in predefined variables (type \"gn help <variable>\" "
  50                "for more details):\n");
  51   for (const auto& builtin : variables::GetBuiltinVariables())
  52     PrintShortHelp(builtin.second.help_short);
  53
  54   // Target variables.
  55   OutputString("\nVariables you set in targets (type \"gn help <variable>\" "
  56                "for more details):\n");
  57   for (const auto& target : variables::GetTargetVariables())
  58     PrintShortHelp(target.second.help_short);
  59
  60   OutputString("\nOther help topics:\n");
  61   PrintShortHelp("all: Print all the help at once");
  62   PrintShortHelp("buildargs: How build arguments work.");
  63   PrintShortHelp("dotfile: Info about the toplevel .gn file.");
  64   PrintShortHelp("grammar: Formal grammar for GN build files.");
  65   PrintShortHelp(
  66       "input_conversion: Processing input from exec_script and read_file.");
  67   PrintShortHelp("label_pattern: Matching more than one label.");
  68   PrintShortHelp("runtime_deps: How runtime dependency computation works.");
  69   PrintShortHelp("source_expansion: Map sources to outputs for scripts.");
  70   PrintShortHelp("switches: Show available command-line switches.");
  71 }
  72
  73 void PrintSwitchHelp() {
  74   const base::CommandLine* cmdline = base::CommandLine::ForCurrentProcess();
  75   bool use_markdown = cmdline->HasSwitch(switches::kMarkdown);
  76
  77   OutputString("Available global switches\n", DECORATION_YELLOW);
  78   OutputString(
  79       "  Do \"gn help --the_switch_you_want_help_on\" for more. Individual\n"
  80       "  commands may take command-specific switches not listed here. See the\n"
  81       "  help on your specific command for more.\n\n");
  82
  83   if (use_markdown)
  84     OutputString("```\n\n", DECORATION_NONE);
  85
  86   for (const auto& s : switches::GetSwitches())
  87     PrintShortHelp(s.second.short_help);
  88
  89   if (use_markdown)
  90     OutputString("\n```\n", DECORATION_NONE);
  91 }
  92
  93 void PrintAllHelp() {
  94   const base::CommandLine* cmdline = base::CommandLine::ForCurrentProcess();
  95   if (cmdline->HasSwitch(switches::kMarkdown)) {
  96     OutputString("# GN Reference\n\n");
  97
  98     // TODO: https://code.google.com/p/gitiles/issues/detail?id=75
  99     // Gitiles crashes when rendering the table of contents, so we must omit
 100     // it until the bug is fixed.
 101     // OutputString("[TOC]\n\n");
 102     OutputString("*This page is automatically generated from* "
 103                  "`gn help --markdown all`.\n\n");
 104   } else {
 105     PrintToplevelHelp();
 106   }
 107
 108   for (const auto& s : switches::GetSwitches())
 109     PrintLongHelp(s.second.long_help);
 110
 111   for (const auto& c: commands::GetCommands())
 112     PrintLongHelp(c.second.help);
 113
 114   for (const auto& f: functions::GetFunctions())
 115     PrintLongHelp(f.second.help);
 116
 117   for (const auto& v: variables::GetBuiltinVariables())
 118     PrintLongHelp(v.second.help);
 119
 120   for (const auto& v: variables::GetTargetVariables())
 121     PrintLongHelp(v.second.help);
 122
 123   PrintLongHelp(kBuildArgs_Help);
 124   PrintLongHelp(kDotfile_Help);
 125   PrintLongHelp(kGrammar_Help);
 126   PrintLongHelp(kInputConversion_Help);
 127   PrintLongHelp(kLabelPattern_Help);
 128   PrintLongHelp(kRuntimeDeps_Help);
 129   PrintLongHelp(kSourceExpansion_Help);
 130   PrintSwitchHelp();
 131 }
 132
 133 // Prints help on the given switch. There should be no leading hyphens. Returns
 134 // true if the switch was found and help was printed. False means the switch is
 135 // unknown.
 136 bool PrintHelpOnSwitch(const std::string& what) {
 137   const switches::SwitchInfoMap& all = switches::GetSwitches();
 138   switches::SwitchInfoMap::const_iterator found =
 139       all.find(base::StringPiece(what));
 140   if (found == all.end())
 141     return false;
 142   PrintLongHelp(found->second.long_help);
 143   return true;
 144 }
 145
 146 }  // namespace
 147
 148 const char kHelp[] = "help";
 149 const char kHelp_HelpShort[] =
 150     "help: Does what you think.";
 151 const char kHelp_Help[] =
 152     "gn help <anything>\n"
 153     "  Yo dawg, I heard you like help on your help so I put help on the help\n"
 154     "  in the help.\n";
 155
 156 int RunHelp(const std::vector<std::string>& args) {
 157   std::string what;
 158   if (args.size() == 0) {
 159     // If no argument is specified, check for switches to allow things like
 160     // "gn help --args" for help on the args switch.
 161     const base::CommandLine::SwitchMap& switches =
 162         base::CommandLine::ForCurrentProcess()->GetSwitches();
 163     if (switches.empty()) {
 164       // Still nothing, show help overview.
 165       PrintToplevelHelp();
 166       return 0;
 167     }
 168
 169     // Switch help needs to be done separately. The CommandLine will strip the
 170     // switch separators so --args will come out as "args" which is then
 171     // ambiguous with the variable named "args".
 172     if (!PrintHelpOnSwitch(switches.begin()->first))
 173       PrintToplevelHelp();
 174     return 0;
 175   } else {
 176     what = args[0];
 177   }
 178
 179   // Check commands.
 180   const commands::CommandInfoMap& command_map = commands::GetCommands();
 181   commands::CommandInfoMap::const_iterator found_command =
 182       command_map.find(what);
 183   if (found_command != command_map.end()) {
 184     PrintLongHelp(found_command->second.help);
 185     return 0;
 186   }
 187
 188   // Check functions.
 189   const functions::FunctionInfoMap& function_map = functions::GetFunctions();
 190   functions::FunctionInfoMap::const_iterator found_function =
 191       function_map.find(what);
 192   if (found_function != function_map.end()) {
 193     PrintLongHelp(found_function->second.help);
 194     return 0;
 195   }
 196
 197   // Builtin variables.
 198   const variables::VariableInfoMap& builtin_vars =
 199       variables::GetBuiltinVariables();
 200   variables::VariableInfoMap::const_iterator found_builtin_var =
 201       builtin_vars.find(what);
 202   if (found_builtin_var != builtin_vars.end()) {
 203     PrintLongHelp(found_builtin_var->second.help);
 204     return 0;
 205   }
 206
 207   // Target variables.
 208   const variables::VariableInfoMap& target_vars =
 209       variables::GetTargetVariables();
 210   variables::VariableInfoMap::const_iterator found_target_var =
 211       target_vars.find(what);
 212   if (found_target_var != target_vars.end()) {
 213     PrintLongHelp(found_target_var->second.help);
 214     return 0;
 215   }
 216
 217   // Random other topics.
 218   if (what == "all") {
 219     PrintAllHelp();
 220     return 0;
 221   }
 222   if (what == "buildargs") {
 223     PrintLongHelp(kBuildArgs_Help);
 224     return 0;
 225   }
 226   if (what == "dotfile") {
 227     PrintLongHelp(kDotfile_Help);
 228     return 0;
 229   }
 230   if (what == "grammar") {
 231     PrintLongHelp(kGrammar_Help);
 232     return 0;
 233   }
 234   if (what == "input_conversion") {
 235     PrintLongHelp(kInputConversion_Help);
 236     return 0;
 237   }
 238   if (what == "label_pattern") {
 239     PrintLongHelp(kLabelPattern_Help);
 240     return 0;
 241   }
 242   if (what == "runtime_deps") {
 243     PrintLongHelp(kRuntimeDeps_Help);
 244     return 0;
 245   }
 246   if (what == "source_expansion") {
 247     PrintLongHelp(kSourceExpansion_Help);
 248     return 0;
 249   }
 250   if (what == "switches") {
 251     PrintSwitchHelp();
 252     return 0;
 253   }
 254
 255   // No help on this.
 256   Err(Location(), "No help on \"" + what + "\".").PrintToStdout();
 257   RunHelp(std::vector<std::string>());
 258   return 1;
 259 }
 260
 261 }  // namespace commands