tools/gn/switches.cc

   1 // Copyright 2014 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 "tools/gn/switches.h"
   6
   7 namespace switches {
   8
   9 const char kArgs[] = "args";
  10 const char kArgs_HelpShort[] =
  11     "--args: Specifies build arguments overrides.";
  12 const char kArgs_Help[] =
  13     "--args: Specifies build arguments overrides.\n"
  14     "\n"
  15     "  See \"gn help buildargs\" for an overview of how build arguments work.\n"
  16     "\n"
  17     "  Most operations take a build directory. The build arguments are taken\n"
  18     "  from the previous build done in that directory. If a command specifies\n"
  19     "  --args, it will override the previous arguments stored in the build\n"
  20     "  directory, and use the specified ones.\n"
  21     "\n"
  22     "  The args specified will be saved to the build directory for subsequent\n"
  23     "  commands. Specifying --args=\"\" will clear all build arguments.\n"
  24     "\n"
  25     "Formatting\n"
  26     "\n"
  27     "  The value of the switch is interpreted in GN syntax. For typical usage\n"
  28     "  of string arguments, you will need to be careful about escaping of\n"
  29     "  quotes.\n"
  30     "\n"
  31     "Examples\n"
  32     "\n"
  33     "  gn gen out/Default --args=\"foo=\\\"bar\\\"\"\n"
  34     "\n"
  35     "  gn gen out/Default --args='foo=\"bar\" enable=true blah=7'\n"
  36     "\n"
  37     "  gn check out/Default --args=\"\"\n"
  38     "    Clears existing build args from the directory.\n"
  39     "\n"
  40     "  gn desc out/Default --args=\"some_list=[1, false, \\\"foo\\\"]\"\n";
  41
  42 #define COLOR_HELP_LONG \
  43     "--[no]color: Forces colored output on or off.\n"\
  44     "\n"\
  45     "  Normally GN will try to detect whether it is outputting to a terminal\n"\
  46     "  and will enable or disable color accordingly. Use of these switches\n"\
  47     "  will override the default.\n"\
  48     "\n"\
  49     "Examples\n"\
  50     "\n"\
  51     "  gn gen out/Default --color\n"\
  52     "\n"\
  53     "  gn gen out/Default --nocolor\n"
  54 const char kColor[] = "color";
  55 const char kColor_HelpShort[] =
  56     "--color: Force colored output.";
  57 const char kColor_Help[] = COLOR_HELP_LONG;
  58
  59 const char kDotfile[] = "dotfile";
  60 const char kDotfile_HelpShort[] =
  61     "--dotfile: override the name of the \".gn\" file.";
  62 const char kDotfile_Help[] =
  63     "--dotfile: override the name of the \".gn\" file.\n"
  64     "\n"
  65     "  Normally GN loads the \".gn\"file  from the source root for some basic\n"
  66     "  configuration (see \"gn help dotfile\"). This flag allows you to\n"
  67     "  use a different file.\n"
  68     "\n"
  69     "  Note that this interacts with \"--root\" in a possibly incorrect way.\n"
  70     "  It would be nice to test the edge cases and document or fix.\n";
  71
  72 const char kMarkdown[] = "markdown";
  73 const char kMarkdown_HelpShort[] =
  74     "--markdown: write the output in the Markdown format.";
  75 const char kMarkdown_Help[] =
  76     "--markdown: write the output in the Markdown format.\n";
  77
  78 const char kNoColor[] = "nocolor";
  79 const char kNoColor_HelpShort[] =
  80     "--nocolor: Force non-colored output.";
  81 const char kNoColor_Help[] = COLOR_HELP_LONG;
  82
  83 const char kQuiet[] = "q";
  84 const char kQuiet_HelpShort[] =
  85     "-q: Quiet mode. Don't print output on success.";
  86 const char kQuiet_Help[] =
  87     "-q: Quiet mode. Don't print output on success.\n"
  88     "\n"
  89     "  This is useful when running as a part of another script.\n";
  90
  91 const char kRoot[] = "root";
  92 const char kRoot_HelpShort[] =
  93     "--root: Explicitly specify source root.";
  94 const char kRoot_Help[] =
  95     "--root: Explicitly specify source root.\n"
  96     "\n"
  97     "  Normally GN will look up in the directory tree from the current\n"
  98     "  directory to find a \".gn\" file. The source root directory specifies\n"
  99     "  the meaning of \"//\" beginning with paths, and the BUILD.gn file\n"
 100     "  in that directory will be the first thing loaded.\n"
 101     "\n"
 102     "  Specifying --root allows GN to do builds in a specific directory\n"
 103     "  regardless of the current directory.\n"
 104     "\n"
 105     "Examples\n"
 106     "\n"
 107     "  gn gen //out/Default --root=/home/baracko/src\n"
 108     "\n"
 109     "  gn desc //out/Default --root=\"C:\\Users\\BObama\\My Documents\\foo\"\n";
 110
 111 const char kThreads[] = "threads";
 112 const char kThreads_HelpShort[] =
 113     "--threads: Specify number of worker threads.";
 114 const char kThreads_Help[] =
 115     "--threads: Specify number of worker threads.\n"
 116     "\n"
 117     "  GN runs many threads to load and run build files. This can make\n"
 118     "  debugging challenging. Or you may want to experiment with different\n"
 119     "  values to see how it affects performance.\n"
 120     "\n"
 121     "  The parameter is the number of worker threads. This does not count the\n"
 122     "  main thread (so there are always at least two).\n"
 123     "\n"
 124     "Examples\n"
 125     "\n"
 126     "  gen gen out/Default --threads=1\n";
 127
 128 const char kTime[] = "time";
 129 const char kTime_HelpShort[] =
 130     "--time: Outputs a summary of how long everything took.";
 131 const char kTime_Help[] =
 132     "--time: Outputs a summary of how long everything took.\n"
 133     "\n"
 134     "  Hopefully self-explanatory.\n"
 135     "\n"
 136     "Examples\n"
 137     "\n"
 138     "  gn gen out/Default --time\n";
 139
 140 const char kTracelog[] = "tracelog";
 141 const char kTracelog_HelpShort[] =
 142     "--tracelog: Writes a Chrome-compatible trace log to the given file.";
 143 const char kTracelog_Help[] =
 144     "--tracelog: Writes a Chrome-compatible trace log to the given file.\n"
 145     "\n"
 146     "  The trace log will show file loads, executions, scripts, and writes.\n"
 147     "  This allows performance analysis of the generation step.\n"
 148     "\n"
 149     "  To view the trace, open Chrome and navigate to \"chrome://tracing/\",\n"
 150     "  then press \"Load\" and specify the file you passed to this parameter.\n"
 151     "\n"
 152     "Examples\n"
 153     "\n"
 154     "  gn gen out/Default --tracelog=mytrace.trace\n";
 155
 156 const char kVerbose[] = "v";
 157 const char kVerbose_HelpShort[] =
 158     "-v: Verbose logging.";
 159 const char kVerbose_Help[] =
 160     "-v: Verbose logging.\n"
 161     "\n"
 162     "  This will spew logging events to the console for debugging issues.\n"
 163     "  Good luck!\n";
 164
 165 const char kVersion[] = "version";
 166 const char kVersion_HelpShort[] =
 167     "--version: Prints the GN version number and exits.";
 168 // It's impossible to see this since gn_main prints the version and exits
 169 // immediately if this switch is used.
 170 const char kVersion_Help[] = "";
 171
 172 // -----------------------------------------------------------------------------
 173
 174 SwitchInfo::SwitchInfo()
 175     : short_help(""),
 176       long_help("") {
 177 }
 178
 179 SwitchInfo::SwitchInfo(const char* short_help, const char* long_help)
 180     : short_help(short_help),
 181       long_help(long_help) {
 182 }
 183
 184 #define INSERT_VARIABLE(var) \
 185     info_map[k##var] = SwitchInfo(k##var##_HelpShort, k##var##_Help);
 186
 187 const SwitchInfoMap& GetSwitches() {
 188   static SwitchInfoMap info_map;
 189   if (info_map.empty()) {
 190     INSERT_VARIABLE(Args)
 191     INSERT_VARIABLE(Color)
 192     INSERT_VARIABLE(Dotfile)
 193     INSERT_VARIABLE(Markdown)
 194     INSERT_VARIABLE(NoColor)
 195     INSERT_VARIABLE(Root)
 196     INSERT_VARIABLE(Quiet)
 197     INSERT_VARIABLE(Time)
 198     INSERT_VARIABLE(Tracelog)
 199     INSERT_VARIABLE(Verbose)
 200     INSERT_VARIABLE(Version)
 201   }
 202   return info_map;
 203 }
 204
 205 #undef INSERT_VARIABLE
 206
 207 }  // namespace switches