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(kGrammar_Help);
 124   PrintLongHelp(kInputConversion_Help);
 125   PrintLongHelp(kLabelPattern_Help);
 126   PrintLongHelp(kSourceExpansion_Help);
 127   PrintSwitchHelp();
 128 }
 129
 130 // Prints help on the given switch. There should be no leading hyphens. Returns
 131 // true if the switch was found and help was printed. False means the switch is
 132 // unknown.
 133 bool PrintHelpOnSwitch(const std::string& what) {
 134   const switches::SwitchInfoMap& all = switches::GetSwitches();
 135   switches::SwitchInfoMap::const_iterator found =
 136       all.find(base::StringPiece(what));
 137   if (found == all.end())
 138     return false;
 139   PrintLongHelp(found->second.long_help);
 140   return true;
 141 }
 142
 143 }  // namespace
 144
 145 const char kHelp[] = "help";
 146 const char kHelp_HelpShort[] =
 147     "help: Does what you think.";
 148 const char kHelp_Help[] =
 149     "gn help <anything>\n"
 150     "  Yo dawg, I heard you like help on your help so I put help on the help\n"
 151     "  in the help.\n";
 152
 153 int RunHelp(const std::vector<std::string>& args) {
 154   std::string what;
 155   if (args.size() == 0) {
 156     // If no argument is specified, check for switches to allow things like
 157     // "gn help --args" for help on the args switch.
 158     const base::CommandLine::SwitchMap& switches =
 159         base::CommandLine::ForCurrentProcess()->GetSwitches();
 160     if (switches.empty()) {
 161       // Still nothing, show help overview.
 162       PrintToplevelHelp();
 163       return 0;
 164     }
 165
 166     // Switch help needs to be done separately. The CommandLine will strip the
 167     // switch separators so --args will come out as "args" which is then
 168     // ambiguous with the variable named "args".
 169     if (!PrintHelpOnSwitch(switches.begin()->first))
 170       PrintToplevelHelp();
 171     return 0;
 172   } else {
 173     what = args[0];
 174   }
 175
 176   // Check commands.
 177   const commands::CommandInfoMap& command_map = commands::GetCommands();
 178   commands::CommandInfoMap::const_iterator found_command =
 179       command_map.find(what);
 180   if (found_command != command_map.end()) {
 181     PrintLongHelp(found_command->second.help);
 182     return 0;
 183   }
 184
 185   // Check functions.
 186   const functions::FunctionInfoMap& function_map = functions::GetFunctions();
 187   functions::FunctionInfoMap::const_iterator found_function =
 188       function_map.find(what);
 189   if (found_function != function_map.end()) {
 190     PrintLongHelp(found_function->second.help);
 191     return 0;
 192   }
 193
 194   // Builtin variables.
 195   const variables::VariableInfoMap& builtin_vars =
 196       variables::GetBuiltinVariables();
 197   variables::VariableInfoMap::const_iterator found_builtin_var =
 198       builtin_vars.find(what);
 199   if (found_builtin_var != builtin_vars.end()) {
 200     PrintLongHelp(found_builtin_var->second.help);
 201     return 0;
 202   }
 203
 204   // Target variables.
 205   const variables::VariableInfoMap& target_vars =
 206       variables::GetTargetVariables();
 207   variables::VariableInfoMap::const_iterator found_target_var =
 208       target_vars.find(what);
 209   if (found_target_var != target_vars.end()) {
 210     PrintLongHelp(found_target_var->second.help);
 211     return 0;
 212   }
 213
 214   // Random other topics.
 215   if (what == "all") {
 216     PrintAllHelp();
 217     return 0;
 218   }
 219   if (what == "buildargs") {
 220     PrintLongHelp(kBuildArgs_Help);
 221     return 0;
 222   }
 223   if (what == "dotfile") {
 224     PrintLongHelp(kDotfile_Help);
 225     return 0;
 226   }
 227   if (what == "grammar") {
 228     PrintLongHelp(kGrammar_Help);
 229     return 0;
 230   }
 231   if (what == "input_conversion") {
 232     PrintLongHelp(kInputConversion_Help);
 233     return 0;
 234   }
 235   if (what == "label_pattern") {
 236     PrintLongHelp(kLabelPattern_Help);
 237     return 0;
 238   }
 239   if (what == "source_expansion") {
 240     PrintLongHelp(kSourceExpansion_Help);
 241     return 0;
 242   }
 243   if (what == "switches") {
 244     PrintSwitchHelp();
 245     return 0;
 246   }
 247
 248   // No help on this.
 249   Err(Location(), "No help on \"" + what + "\".").PrintToStdout();
 250   RunHelp(std::vector<std::string>());
 251   return 1;
 252 }
 253
 254 }  // namespace commands