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