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