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("buildargs: How build arguments work.");
  61   PrintShortHelp("dotfile: Info about the toplevel .gn file.");
  62   PrintShortHelp("grammar: Formal grammar for GN build files.");
  63   PrintShortHelp("label_pattern: Matching more than one label.");
  64   PrintShortHelp(
  65       "input_conversion: Processing input from exec_script and read_file.");
  66   PrintShortHelp("source_expansion: Map sources to outputs for scripts.");
  67   PrintShortHelp("switches: Show available command-line switches.");
  68 }
  69
  70 void PrintSwitchHelp() {
  71   OutputString("Available global switches\n", DECORATION_YELLOW);
  72   OutputString(
  73       "  Do \"gn help --the_switch_you_want_help_on\" for more. Individual\n"
  74       "  commands may take command-specific switches not listed here. See the\n"
  75       "  help on your specific command for more.\n\n");
  76
  77   for (const auto& s : switches::GetSwitches())
  78     PrintShortHelp(s.second.short_help);
  79 }
  80
  81 // Prints help on the given switch. There should be no leading hyphens. Returns
  82 // true if the switch was found and help was printed. False means the switch is
  83 // unknown.
  84 bool PrintHelpOnSwitch(const std::string& what) {
  85   const switches::SwitchInfoMap& all = switches::GetSwitches();
  86   switches::SwitchInfoMap::const_iterator found =
  87       all.find(base::StringPiece(what));
  88   if (found == all.end())
  89     return false;
  90   PrintLongHelp(found->second.long_help);
  91   return true;
  92 }
  93
  94 }  // namespace
  95
  96 const char kHelp[] = "help";
  97 const char kHelp_HelpShort[] =
  98     "help: Does what you think.";
  99 const char kHelp_Help[] =
 100     "gn help <anything>\n"
 101     "  Yo dawg, I heard you like help on your help so I put help on the help\n"
 102     "  in the help.\n";
 103
 104 int RunHelp(const std::vector<std::string>& args) {
 105   std::string what;
 106   if (args.size() == 0) {
 107     // If no argument is specified, check for switches to allow things like
 108     // "gn help --args" for help on the args switch.
 109     const base::CommandLine::SwitchMap& switches =
 110         base::CommandLine::ForCurrentProcess()->GetSwitches();
 111     if (switches.empty()) {
 112       // Still nothing, show help overview.
 113       PrintToplevelHelp();
 114       return 0;
 115     }
 116
 117     // Switch help needs to be done separately. The CommandLine will strip the
 118     // switch separators so --args will come out as "args" which is then
 119     // ambiguous with the variable named "args".
 120     if (!PrintHelpOnSwitch(switches.begin()->first))
 121       PrintToplevelHelp();
 122     return 0;
 123   } else {
 124     what = args[0];
 125   }
 126
 127   // Check commands.
 128   const commands::CommandInfoMap& command_map = commands::GetCommands();
 129   commands::CommandInfoMap::const_iterator found_command =
 130       command_map.find(what);
 131   if (found_command != command_map.end()) {
 132     PrintLongHelp(found_command->second.help);
 133     return 0;
 134   }
 135
 136   // Check functions.
 137   const functions::FunctionInfoMap& function_map = functions::GetFunctions();
 138   functions::FunctionInfoMap::const_iterator found_function =
 139       function_map.find(what);
 140   if (found_function != function_map.end()) {
 141     PrintLongHelp(found_function->second.help);
 142     return 0;
 143   }
 144
 145   // Builtin variables.
 146   const variables::VariableInfoMap& builtin_vars =
 147       variables::GetBuiltinVariables();
 148   variables::VariableInfoMap::const_iterator found_builtin_var =
 149       builtin_vars.find(what);
 150   if (found_builtin_var != builtin_vars.end()) {
 151     PrintLongHelp(found_builtin_var->second.help);
 152     return 0;
 153   }
 154
 155   // Target variables.
 156   const variables::VariableInfoMap& target_vars =
 157       variables::GetTargetVariables();
 158   variables::VariableInfoMap::const_iterator found_target_var =
 159       target_vars.find(what);
 160   if (found_target_var != target_vars.end()) {
 161     PrintLongHelp(found_target_var->second.help);
 162     return 0;
 163   }
 164
 165   // Random other topics.
 166   if (what == "buildargs") {
 167     PrintLongHelp(kBuildArgs_Help);
 168     return 0;
 169   }
 170   if (what == "dotfile") {
 171     PrintLongHelp(kDotfile_Help);
 172     return 0;
 173   }
 174   if (what == "grammar") {
 175     PrintLongHelp(kGrammar_Help);
 176     return 0;
 177   }
 178   if (what == "input_conversion") {
 179     PrintLongHelp(kInputConversion_Help);
 180     return 0;
 181   }
 182   if (what == "label_pattern") {
 183     PrintLongHelp(kLabelPattern_Help);
 184     return 0;
 185   }
 186   if (what == "source_expansion") {
 187     PrintLongHelp(kSourceExpansion_Help);
 188     return 0;
 189   }
 190   if (what == "switches") {
 191     PrintSwitchHelp();
 192     return 0;
 193   }
 194
 195   // No help on this.
 196   Err(Location(), "No help on \"" + what + "\".").PrintToStdout();
 197   RunHelp(std::vector<std::string>());
 198   return 1;
 199 }
 200
 201 }  // namespace commands