OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #include "tools/gn/switches.h" | 5 #include "tools/gn/switches.h" |
6 | 6 |
7 namespace switches { | 7 namespace switches { |
8 | 8 |
9 const char kArgs[] = "args"; | 9 const char kArgs[] = "args"; |
10 const char kArgs_HelpShort[] = | 10 const char kArgs_HelpShort[] = |
11 "--args: Specifies build arguments overrides."; | 11 "--args: Specifies build arguments overrides."; |
12 const char kArgs_Help[] = | 12 const char kArgs_Help[] = |
13 "--args: Specifies build arguments overrides.\n" | 13 R"(--args: Specifies build arguments overrides. |
14 "\n" | 14 |
15 " See \"gn help buildargs\" for an overview of how build arguments work.\n" | 15 See "gn help buildargs" for an overview of how build arguments work. |
16 "\n" | 16 |
17 " Most operations take a build directory. The build arguments are taken\n" | 17 Most operations take a build directory. The build arguments are taken from |
18 " from the previous build done in that directory. If a command specifies\n" | 18 the previous build done in that directory. If a command specifies --args, it |
19 " --args, it will override the previous arguments stored in the build\n" | 19 will override the previous arguments stored in the build directory, and use |
20 " directory, and use the specified ones.\n" | 20 the specified ones. |
21 "\n" | 21 |
22 " The args specified will be saved to the build directory for subsequent\n" | 22 The args specified will be saved to the build directory for subsequent |
23 " commands. Specifying --args=\"\" will clear all build arguments.\n" | 23 commands. Specifying --args="" will clear all build arguments. |
24 "\n" | 24 |
25 "Formatting\n" | 25 Formatting |
26 "\n" | 26 |
27 " The value of the switch is interpreted in GN syntax. For typical usage\n" | 27 The value of the switch is interpreted in GN syntax. For typical usage of |
28 " of string arguments, you will need to be careful about escaping of\n" | 28 string arguments, you will need to be careful about escaping of quotes. |
29 " quotes.\n" | 29 |
30 "\n" | 30 Examples |
31 "Examples\n" | 31 |
32 "\n" | 32 gn gen out/Default --args="foo=\"bar\"" |
33 " gn gen out/Default --args=\"foo=\\\"bar\\\"\"\n" | 33 |
34 "\n" | 34 gn gen out/Default --args='foo="bar" enable=true blah=7' |
35 " gn gen out/Default --args='foo=\"bar\" enable=true blah=7'\n" | 35 |
36 "\n" | 36 gn check out/Default --args="" |
37 " gn check out/Default --args=\"\"\n" | 37 Clears existing build args from the directory. |
38 " Clears existing build args from the directory.\n" | 38 |
39 "\n" | 39 gn desc out/Default --args="some_list=[1, false, \"foo\"]" |
40 " gn desc out/Default --args=\"some_list=[1, false, \\\"foo\\\"]\"\n"; | 40 )"; |
41 | 41 |
42 #define COLOR_HELP_LONG \ | 42 #define COLOR_HELP_LONG \ |
43 "--[no]color: Forces colored output on or off.\n"\ | 43 "--[no]color: Forces colored output on or off.\n"\ |
44 "\n"\ | 44 "\n"\ |
45 " Normally GN will try to detect whether it is outputting to a terminal\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"\ | 46 " and will enable or disable color accordingly. Use of these switches\n"\ |
47 " will override the default.\n"\ | 47 " will override the default.\n"\ |
48 "\n"\ | 48 "\n"\ |
49 "Examples\n"\ | 49 "Examples\n"\ |
50 "\n"\ | 50 "\n"\ |
51 " gn gen out/Default --color\n"\ | 51 " gn gen out/Default --color\n"\ |
52 "\n"\ | 52 "\n"\ |
53 " gn gen out/Default --nocolor\n" | 53 " gn gen out/Default --nocolor\n" |
54 const char kColor[] = "color"; | 54 const char kColor[] = "color"; |
55 const char kColor_HelpShort[] = | 55 const char kColor_HelpShort[] = |
56 "--color: Force colored output."; | 56 "--color: Force colored output."; |
57 const char kColor_Help[] = COLOR_HELP_LONG; | 57 const char kColor_Help[] = COLOR_HELP_LONG; |
58 | 58 |
59 const char kDotfile[] = "dotfile"; | 59 const char kDotfile[] = "dotfile"; |
60 const char kDotfile_HelpShort[] = | 60 const char kDotfile_HelpShort[] = |
61 "--dotfile: Override the name of the \".gn\" file."; | 61 "--dotfile: Override the name of the \".gn\" file."; |
62 const char kDotfile_Help[] = | 62 const char kDotfile_Help[] = |
63 "--dotfile: Override the name of the \".gn\" file.\n" | 63 R"(--dotfile: Override the name of the ".gn" file. |
64 "\n" | 64 |
65 " Normally GN loads the \".gn\"file from the source root for some basic\n" | 65 Normally GN loads the ".gn"file from the source root for some basic |
66 " configuration (see \"gn help dotfile\"). This flag allows you to\n" | 66 configuration (see "gn help dotfile"). This flag allows you to |
67 " use a different file.\n" | 67 use a different file. |
68 "\n" | 68 |
69 " Note that this interacts with \"--root\" in a possibly incorrect way.\n" | 69 Note that this interacts with "--root" in a possibly incorrect way. |
70 " It would be nice to test the edge cases and document or fix.\n"; | 70 It would be nice to test the edge cases and document or fix. |
| 71 )"; |
71 | 72 |
72 const char kFailOnUnusedArgs[] = "fail-on-unused-args"; | 73 const char kFailOnUnusedArgs[] = "fail-on-unused-args"; |
73 const char kFailOnUnusedArgs_HelpShort[] = | 74 const char kFailOnUnusedArgs_HelpShort[] = |
74 "--fail-on-unused-args: Treat unused build args as fatal errors."; | 75 "--fail-on-unused-args: Treat unused build args as fatal errors."; |
75 const char kFailOnUnusedArgs_Help[] = | 76 const char kFailOnUnusedArgs_Help[] = |
76 "--fail-on-unused-args: Treat unused build args as fatal errors.\n" | 77 R"(--fail-on-unused-args: Treat unused build args as fatal errors. |
77 "\n" | 78 |
78 " If you set a value in a build's \"gn args\" and never use it in the\n" | 79 If you set a value in a build's "gn args" and never use it in the build (in |
79 " build (in a declare_args() block), GN will normally print an error\n" | 80 a declare_args() block), GN will normally print an error but not fail the |
80 " but not fail the build.\n" | 81 build. |
81 "\n" | 82 |
82 " In many cases engineers would use build args to enable or disable\n" | 83 In many cases engineers would use build args to enable or disable features |
83 " features that would sometimes get removed. It would by annoying to\n" | 84 that would sometimes get removed. It would by annoying to block work for |
84 " block work for typically benign problems. In Chrome in particular,\n" | 85 typically benign problems. In Chrome in particular, flags might be configured |
85 " flags might be configured for build bots in a separate infrastructure\n" | 86 for build bots in a separate infrastructure repository, or a declare_args |
86 " repository, or a declare_args block might be changed in a third party\n" | 87 block might be changed in a third party repository. Treating these errors as |
87 " repository. Treating these errors as blocking forced complex multi-\n" | 88 blocking forced complex multi- way patches to land what would otherwise be |
88 " way patches to land what would otherwise be simple changes.\n" | 89 simple changes. |
89 "\n" | 90 |
90 " In some cases, such concerns are not as important, and a mismatch\n" | 91 In some cases, such concerns are not as important, and a mismatch in build |
91 " in build flags between the invoker of the build and the build files\n" | 92 flags between the invoker of the build and the build files represents a |
92 " represents a critical mismatch that should be immediately fixed. Such\n" | 93 critical mismatch that should be immediately fixed. Such users can set this |
93 " users can set this flag to force GN to fail in that case.\n"; | 94 flag to force GN to fail in that case. |
| 95 )"; |
94 | 96 |
95 const char kMarkdown[] = "markdown"; | 97 const char kMarkdown[] = "markdown"; |
96 const char kMarkdown_HelpShort[] = | 98 const char kMarkdown_HelpShort[] = |
97 "--markdown: Write help output in the Markdown format."; | 99 "--markdown: Write help output in the Markdown format."; |
98 const char kMarkdown_Help[] = | 100 const char kMarkdown_Help[] = |
99 "--markdown: Write help output in the Markdown format.\n"; | 101 "--markdown: Write help output in the Markdown format.\n"; |
100 | 102 |
101 const char kNoColor[] = "nocolor"; | 103 const char kNoColor[] = "nocolor"; |
102 const char kNoColor_HelpShort[] = | 104 const char kNoColor_HelpShort[] = |
103 "--nocolor: Force non-colored output."; | 105 "--nocolor: Force non-colored output."; |
104 const char kNoColor_Help[] = COLOR_HELP_LONG; | 106 const char kNoColor_Help[] = COLOR_HELP_LONG; |
105 | 107 |
106 const char kScriptExecutable[] = "script-executable"; | 108 const char kScriptExecutable[] = "script-executable"; |
107 const char kScriptExecutable_HelpShort[] = | 109 const char kScriptExecutable_HelpShort[] = |
108 "--script-executable: Set the executable used to execute scripts."; | 110 "--script-executable: Set the executable used to execute scripts."; |
109 const char kScriptExecutable_Help[] = | 111 const char kScriptExecutable_Help[] = |
110 "--script-executable: Set the executable used to execute scripts.\n" | 112 R"(--script-executable: Set the executable used to execute scripts. |
111 "\n" | 113 |
112 " By default GN searches the PATH for Python to execute scripts in\n" | 114 By default GN searches the PATH for Python to execute scripts in action |
113 " action targets and exec_script calls. This flag allows the\n" | 115 targets and exec_script calls. This flag allows the specification of a |
114 " specification of a specific Python executable or potentially\n" | 116 specific Python executable or potentially a different language |
115 " a different language interpreter.\n"; | 117 interpreter. |
| 118 )"; |
116 | 119 |
117 const char kQuiet[] = "q"; | 120 const char kQuiet[] = "q"; |
118 const char kQuiet_HelpShort[] = | 121 const char kQuiet_HelpShort[] = |
119 "-q: Quiet mode. Don't print output on success."; | 122 "-q: Quiet mode. Don't print output on success."; |
120 const char kQuiet_Help[] = | 123 const char kQuiet_Help[] = |
121 "-q: Quiet mode. Don't print output on success.\n" | 124 R"(-q: Quiet mode. Don't print output on success. |
122 "\n" | 125 |
123 " This is useful when running as a part of another script.\n"; | 126 This is useful when running as a part of another script. |
| 127 )"; |
124 | 128 |
125 const char kRoot[] = "root"; | 129 const char kRoot[] = "root"; |
126 const char kRoot_HelpShort[] = | 130 const char kRoot_HelpShort[] = |
127 "--root: Explicitly specify source root."; | 131 "--root: Explicitly specify source root."; |
128 const char kRoot_Help[] = | 132 const char kRoot_Help[] = |
129 "--root: Explicitly specify source root.\n" | 133 R"(--root: Explicitly specify source root. |
130 "\n" | 134 |
131 " Normally GN will look up in the directory tree from the current\n" | 135 Normally GN will look up in the directory tree from the current directory to |
132 " directory to find a \".gn\" file. The source root directory specifies\n" | 136 find a ".gn" file. The source root directory specifies the meaning of "//" |
133 " the meaning of \"//\" beginning with paths, and the BUILD.gn file\n" | 137 beginning with paths, and the BUILD.gn file in that directory will be the |
134 " in that directory will be the first thing loaded.\n" | 138 first thing loaded. |
135 "\n" | 139 |
136 " Specifying --root allows GN to do builds in a specific directory\n" | 140 Specifying --root allows GN to do builds in a specific directory regardless |
137 " regardless of the current directory.\n" | 141 of the current directory. |
138 "\n" | 142 |
139 "Examples\n" | 143 Examples |
140 "\n" | 144 |
141 " gn gen //out/Default --root=/home/baracko/src\n" | 145 gn gen //out/Default --root=/home/baracko/src |
142 "\n" | 146 |
143 " gn desc //out/Default --root=\"C:\\Users\\BObama\\My Documents\\foo\"\n"; | 147 gn desc //out/Default --root="C:\Users\BObama\My Documents\foo" |
| 148 )"; |
144 | 149 |
145 const char kRuntimeDepsListFile[] = "runtime-deps-list-file"; | 150 const char kRuntimeDepsListFile[] = "runtime-deps-list-file"; |
146 const char kRuntimeDepsListFile_HelpShort[] = | 151 const char kRuntimeDepsListFile_HelpShort[] = |
147 "--runtime-deps-list-file: Save runtime dependencies for targets in file."; | 152 "--runtime-deps-list-file: Save runtime dependencies for targets in file."; |
148 const char kRuntimeDepsListFile_Help[] = | 153 const char kRuntimeDepsListFile_Help[] = |
149 "--runtime-deps-list-file: Save runtime dependencies for targets in file.\n" | 154 R"(--runtime-deps-list-file: Save runtime dependencies for targets in file. |
150 "\n" | 155 |
151 " --runtime-deps-list-file=<filename>\n" | 156 --runtime-deps-list-file=<filename> |
152 "\n" | 157 |
153 " Where <filename> is a text file consisting of the labels, one per\n" | 158 Where <filename> is a text file consisting of the labels, one per line, of |
154 " line, of the targets for which runtime dependencies are desired.\n" | 159 the targets for which runtime dependencies are desired. |
155 "\n" | 160 |
156 " See \"gn help runtime_deps\" for a description of how runtime\n" | 161 See "gn help runtime_deps" for a description of how runtime dependencies are |
157 " dependencies are computed.\n" | 162 computed. |
158 "\n" | 163 |
159 "Runtime deps output file\n" | 164 Runtime deps output file |
160 "\n" | 165 |
161 " For each target requested, GN will write a separate runtime dependency\n" | 166 For each target requested, GN will write a separate runtime dependency file. |
162 " file. The runtime dependency file will be in the output directory\n" | 167 The runtime dependency file will be in the output directory alongside the |
163 " alongside the output file of the target, with a \".runtime_deps\"\n" | 168 output file of the target, with a ".runtime_deps" extension. For example, if |
164 " extension. For example, if the target \"//foo:bar\" is listed in the\n" | 169 the target "//foo:bar" is listed in the input file, and that target produces |
165 " input file, and that target produces an output file \"bar.so\", GN\n" | 170 an output file "bar.so", GN will create a file "bar.so.runtime_deps" in the |
166 " will create a file \"bar.so.runtime_deps\" in the build directory.\n" | 171 build directory. |
167 "\n" | 172 |
168 " If a source set, action, copy, or group is listed, the runtime deps\n" | 173 If a source set, action, copy, or group is listed, the runtime deps file will |
169 " file will correspond to the .stamp file corresponding to that target.\n" | 174 correspond to the .stamp file corresponding to that target. This is probably |
170 " This is probably not useful; the use-case for this feature is\n" | 175 not useful; the use-case for this feature is generally executable targets. |
171 " generally executable targets.\n" | 176 |
172 "\n" | 177 The runtime dependency file will list one file per line, with no escaping. |
173 " The runtime dependency file will list one file per line, with no\n" | 178 The files will be relative to the root_build_dir. The first line of the file |
174 " escaping. The files will be relative to the root_build_dir. The first\n" | 179 will be the main output file of the target itself (in the above example, |
175 " line of the file will be the main output file of the target itself\n" | 180 "bar.so"). |
176 " (in the above example, \"bar.so\").\n"; | 181 )"; |
177 | 182 |
178 const char kThreads[] = "threads"; | 183 const char kThreads[] = "threads"; |
179 const char kThreads_HelpShort[] = | 184 const char kThreads_HelpShort[] = |
180 "--threads: Specify number of worker threads."; | 185 "--threads: Specify number of worker threads."; |
181 const char kThreads_Help[] = | 186 const char kThreads_Help[] = |
182 "--threads: Specify number of worker threads.\n" | 187 R"(--threads: Specify number of worker threads. |
183 "\n" | 188 |
184 " GN runs many threads to load and run build files. This can make\n" | 189 GN runs many threads to load and run build files. This can make debugging |
185 " debugging challenging. Or you may want to experiment with different\n" | 190 challenging. Or you may want to experiment with different values to see how |
186 " values to see how it affects performance.\n" | 191 it affects performance. |
187 "\n" | 192 |
188 " The parameter is the number of worker threads. This does not count the\n" | 193 The parameter is the number of worker threads. This does not count the main |
189 " main thread (so there are always at least two).\n" | 194 thread (so there are always at least two). |
190 "\n" | 195 |
191 "Examples\n" | 196 Examples |
192 "\n" | 197 |
193 " gen gen out/Default --threads=1\n"; | 198 gen gen out/Default --threads=1 |
| 199 )"; |
194 | 200 |
195 const char kTime[] = "time"; | 201 const char kTime[] = "time"; |
196 const char kTime_HelpShort[] = | 202 const char kTime_HelpShort[] = |
197 "--time: Outputs a summary of how long everything took."; | 203 "--time: Outputs a summary of how long everything took."; |
198 const char kTime_Help[] = | 204 const char kTime_Help[] = |
199 "--time: Outputs a summary of how long everything took.\n" | 205 R"(--time: Outputs a summary of how long everything took. |
200 "\n" | 206 |
201 " Hopefully self-explanatory.\n" | 207 Hopefully self-explanatory. |
202 "\n" | 208 |
203 "Examples\n" | 209 Examples |
204 "\n" | 210 |
205 " gn gen out/Default --time\n"; | 211 gn gen out/Default --time |
| 212 )"; |
206 | 213 |
207 const char kTracelog[] = "tracelog"; | 214 const char kTracelog[] = "tracelog"; |
208 const char kTracelog_HelpShort[] = | 215 const char kTracelog_HelpShort[] = |
209 "--tracelog: Writes a Chrome-compatible trace log to the given file."; | 216 "--tracelog: Writes a Chrome-compatible trace log to the given file."; |
210 const char kTracelog_Help[] = | 217 const char kTracelog_Help[] = |
211 "--tracelog: Writes a Chrome-compatible trace log to the given file.\n" | 218 R"(--tracelog: Writes a Chrome-compatible trace log to the given file. |
212 "\n" | 219 |
213 " The trace log will show file loads, executions, scripts, and writes.\n" | 220 The trace log will show file loads, executions, scripts, and writes. This |
214 " This allows performance analysis of the generation step.\n" | 221 allows performance analysis of the generation step. |
215 "\n" | 222 |
216 " To view the trace, open Chrome and navigate to \"chrome://tracing/\",\n" | 223 To view the trace, open Chrome and navigate to "chrome://tracing/", then |
217 " then press \"Load\" and specify the file you passed to this parameter.\n" | 224 press "Load" and specify the file you passed to this parameter. |
218 "\n" | 225 |
219 "Examples\n" | 226 Examples |
220 "\n" | 227 |
221 " gn gen out/Default --tracelog=mytrace.trace\n"; | 228 gn gen out/Default --tracelog=mytrace.trace |
| 229 )"; |
222 | 230 |
223 const char kVerbose[] = "v"; | 231 const char kVerbose[] = "v"; |
224 const char kVerbose_HelpShort[] = | 232 const char kVerbose_HelpShort[] = |
225 "-v: Verbose logging."; | 233 "-v: Verbose logging."; |
226 const char kVerbose_Help[] = | 234 const char kVerbose_Help[] = |
227 "-v: Verbose logging.\n" | 235 R"(-v: Verbose logging. |
228 "\n" | 236 |
229 " This will spew logging events to the console for debugging issues.\n" | 237 This will spew logging events to the console for debugging issues. |
230 " Good luck!\n"; | 238 |
| 239 Good luck! |
| 240 )"; |
231 | 241 |
232 const char kVersion[] = "version"; | 242 const char kVersion[] = "version"; |
233 const char kVersion_HelpShort[] = | 243 const char kVersion_HelpShort[] = |
234 "--version: Prints the GN version number and exits."; | 244 "--version: Prints the GN version number and exits."; |
235 // It's impossible to see this since gn_main prints the version and exits | 245 // It's impossible to see this since gn_main prints the version and exits |
236 // immediately if this switch is used. | 246 // immediately if this switch is used. |
237 const char kVersion_Help[] = ""; | 247 const char kVersion_Help[] = ""; |
238 | 248 |
239 const char kAllToolchains[] = "all-toolchains"; | 249 const char kAllToolchains[] = "all-toolchains"; |
240 | 250 |
(...skipping 30 matching lines...) Expand all Loading... |
271 INSERT_VARIABLE(Tracelog) | 281 INSERT_VARIABLE(Tracelog) |
272 INSERT_VARIABLE(Verbose) | 282 INSERT_VARIABLE(Verbose) |
273 INSERT_VARIABLE(Version) | 283 INSERT_VARIABLE(Version) |
274 } | 284 } |
275 return info_map; | 285 return info_map; |
276 } | 286 } |
277 | 287 |
278 #undef INSERT_VARIABLE | 288 #undef INSERT_VARIABLE |
279 | 289 |
280 } // namespace switches | 290 } // namespace switches |
OLD | NEW |