Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(307)

Side by Side Diff: tools/gn/variables.cc

Issue 2481423002: Convert gn docstrings to C++11 raw strings. (Closed)
Patch Set: Fixes Created 4 years, 1 month ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « tools/gn/switches.cc ('k') | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. 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 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/variables.h" 5 #include "tools/gn/variables.h"
6 6
7 namespace variables { 7 namespace variables {
8 8
9 // Built-in variables ---------------------------------------------------------- 9 // Built-in variables ----------------------------------------------------------
10 10
11 const char kHostCpu[] = "host_cpu"; 11 const char kHostCpu[] = "host_cpu";
12 const char kHostCpu_HelpShort[] = 12 const char kHostCpu_HelpShort[] =
13 "host_cpu: [string] The processor architecture that GN is running on."; 13 "host_cpu: [string] The processor architecture that GN is running on.";
14 const char kHostCpu_Help[] = 14 const char kHostCpu_Help[] =
15 "host_cpu: The processor architecture that GN is running on.\n" 15 R"(host_cpu: The processor architecture that GN is running on.
16 "\n" 16
17 " This is value is exposed so that cross-compile toolchains can\n" 17 This is value is exposed so that cross-compile toolchains can access the host
18 " access the host architecture when needed.\n" 18 architecture when needed.
19 "\n" 19
20 " The value should generally be considered read-only, but it can be\n" 20 The value should generally be considered read-only, but it can be overriden
21 " overriden in order to handle unusual cases where there might\n" 21 in order to handle unusual cases where there might be multiple plausible
22 " be multiple plausible values for the host architecture (e.g., if\n" 22 values for the host architecture (e.g., if you can do either 32-bit or 64-bit
23 " you can do either 32-bit or 64-bit builds). The value is not used\n" 23 builds). The value is not used internally by GN for any purpose.
24 " internally by GN for any purpose.\n" 24
25 "\n" 25 Some possible values
26 "Some possible values:\n" 26
27 " - \"x64\"\n" 27 - "x64"
28 " - \"x86\"\n"; 28 - "x86"
29 )";
29 30
30 const char kHostOs[] = "host_os"; 31 const char kHostOs[] = "host_os";
31 const char kHostOs_HelpShort[] = 32 const char kHostOs_HelpShort[] =
32 "host_os: [string] The operating system that GN is running on."; 33 "host_os: [string] The operating system that GN is running on.";
33 const char kHostOs_Help[] = 34 const char kHostOs_Help[] =
34 "host_os: [string] The operating system that GN is running on.\n" 35 R"(host_os: [string] The operating system that GN is running on.
35 "\n" 36
36 " This value is exposed so that cross-compiles can access the host\n" 37 This value is exposed so that cross-compiles can access the host build
37 " build system's settings.\n" 38 system's settings.
38 "\n" 39
39 " This value should generally be treated as read-only. It, however,\n" 40 This value should generally be treated as read-only. It, however, is not used
40 " is not used internally by GN for any purpose.\n" 41 internally by GN for any purpose.
41 "\n" 42
42 "Some possible values:\n" 43 Some possible values
43 " - \"linux\"\n" 44
44 " - \"mac\"\n" 45 - "linux"
45 " - \"win\"\n"; 46 - "mac"
47 - "win"
48 )";
46 49
47 const char kInvoker[] = "invoker"; 50 const char kInvoker[] = "invoker";
48 const char kInvoker_HelpShort[] = 51 const char kInvoker_HelpShort[] =
49 "invoker: [string] The invoking scope inside a template."; 52 "invoker: [string] The invoking scope inside a template.";
50 const char kInvoker_Help[] = 53 const char kInvoker_Help[] =
51 "invoker: [string] The invoking scope inside a template.\n" 54 R"(invoker: [string] The invoking scope inside a template.
52 "\n" 55
53 " Inside a template invocation, this variable refers to the scope of\n" 56 Inside a template invocation, this variable refers to the scope of the
54 " the invoker of the template. Outside of template invocations, this\n" 57 invoker of the template. Outside of template invocations, this variable is
55 " variable is undefined.\n" 58 undefined.
56 "\n" 59
57 " All of the variables defined inside the template invocation are\n" 60 All of the variables defined inside the template invocation are accessible as
58 " accessible as members of the \"invoker\" scope. This is the way that\n" 61 members of the "invoker" scope. This is the way that templates read values
59 " templates read values set by the callers.\n" 62 set by the callers.
60 "\n" 63
61 " This is often used with \"defined\" to see if a value is set on the\n" 64 This is often used with "defined" to see if a value is set on the invoking
62 " invoking scope.\n" 65 scope.
63 "\n" 66
64 " See \"gn help template\" for more examples.\n" 67 See "gn help template" for more examples.
65 "\n" 68
66 "Example\n" 69 Example
67 "\n" 70
68 " template(\"my_template\") {\n" 71 template("my_template") {
69 " print(invoker.sources) # Prints [ \"a.cc\", \"b.cc\" ]\n" 72 print(invoker.sources) # Prints [ "a.cc", "b.cc" ]
70 " print(defined(invoker.foo)) # Prints false.\n" 73 print(defined(invoker.foo)) # Prints false.
71 " print(defined(invoker.bar)) # Prints true.\n" 74 print(defined(invoker.bar)) # Prints true.
72 " }\n" 75 }
73 "\n" 76
74 " my_template(\"doom_melon\") {\n" 77 my_template("doom_melon") {
75 " sources = [ \"a.cc\", \"b.cc\" ]\n" 78 sources = [ "a.cc", "b.cc" ]
76 " bar = 123\n" 79 bar = 123
77 " }\n"; 80 }
81 )";
78 82
79 const char kTargetCpu[] = "target_cpu"; 83 const char kTargetCpu[] = "target_cpu";
80 const char kTargetCpu_HelpShort[] = 84 const char kTargetCpu_HelpShort[] =
81 "target_cpu: [string] The desired cpu architecture for the build."; 85 "target_cpu: [string] The desired cpu architecture for the build.";
82 const char kTargetCpu_Help[] = 86 const char kTargetCpu_Help[] =
83 "target_cpu: The desired cpu architecture for the build.\n" 87 R"(target_cpu: The desired cpu architecture for the build.
84 "\n" 88
85 " This value should be used to indicate the desired architecture for\n" 89 This value should be used to indicate the desired architecture for the
86 " the primary objects of the build. It will match the cpu architecture\n" 90 primary objects of the build. It will match the cpu architecture of the
87 " of the default toolchain, but not necessarily the current toolchain.\n" 91 default toolchain, but not necessarily the current toolchain.
88 "\n" 92
89 " In many cases, this is the same as \"host_cpu\", but in the case\n" 93 In many cases, this is the same as "host_cpu", but in the case of
90 " of cross-compiles, this can be set to something different. This\n" 94 cross-compiles, this can be set to something different. This value is
91 " value is different from \"current_cpu\" in that it does not change\n" 95 different from "current_cpu" in that it does not change based on the current
92 " based on the current toolchain. When writing rules, \"current_cpu\"\n" 96 toolchain. When writing rules, "current_cpu" should be used rather than
93 " should be used rather than \"target_cpu\" most of the time.\n" 97 "target_cpu" most of the time.
94 "\n" 98
95 " This value is not used internally by GN for any purpose, so it\n" 99 This value is not used internally by GN for any purpose, so it may be set to
96 " may be set to whatever value is needed for the build.\n" 100 whatever value is needed for the build. GN defaults this value to the empty
97 " GN defaults this value to the empty string (\"\") and the\n" 101 string ("") and the configuration files should set it to an appropriate value
98 " configuration files should set it to an appropriate value\n" 102 (e.g., setting it to the value of "host_cpu") if it is not overridden on the
99 " (e.g., setting it to the value of \"host_cpu\") if it is not\n" 103 command line or in the args.gn file.
100 " overridden on the command line or in the args.gn file.\n" 104
101 "\n" 105 Possible values
102 " Where practical, use one of the following list of common values:\n" 106
103 "\n" 107 - "x86"
104 "Possible values:\n" 108 - "x64"
105 " - \"x86\"\n" 109 - "arm"
106 " - \"x64\"\n" 110 - "arm64"
107 " - \"arm\"\n" 111 - "mipsel"
108 " - \"arm64\"\n" 112 )";
109 " - \"mipsel\"\n";
110 113
111 const char kTargetName[] = "target_name"; 114 const char kTargetName[] = "target_name";
112 const char kTargetName_HelpShort[] = 115 const char kTargetName_HelpShort[] =
113 "target_name: [string] The name of the current target."; 116 "target_name: [string] The name of the current target.";
114 const char kTargetName_Help[] = 117 const char kTargetName_Help[] =
115 "target_name: [string] The name of the current target.\n" 118 R"(target_name: [string] The name of the current target.
116 "\n" 119
117 " Inside a target or template invocation, this variable refers to the\n" 120 Inside a target or template invocation, this variable refers to the name
118 " name given to the target or template invocation. Outside of these,\n" 121 given to the target or template invocation. Outside of these, this variable
119 " this variable is undefined.\n" 122 is undefined.
120 "\n" 123
121 " This is most often used in template definitions to name targets\n" 124 This is most often used in template definitions to name targets defined in
122 " defined in the template based on the name of the invocation. This\n" 125 the template based on the name of the invocation. This is necessary both to
123 " is necessary both to ensure generated targets have unique names and\n" 126 ensure generated targets have unique names and to generate a target with the
124 " to generate a target with the exact name of the invocation that\n" 127 exact name of the invocation that other targets can depend on.
125 " other targets can depend on.\n" 128
126 "\n" 129 Be aware that this value will always reflect the innermost scope. So when
127 " Be aware that this value will always reflect the innermost scope. So\n" 130 defining a target inside a template, target_name will refer to the target
128 " when defining a target inside a template, target_name will refer to\n" 131 rather than the template invocation. To get the name of the template
129 " the target rather than the template invocation. To get the name of the\n" 132 invocation in this case, you should save target_name to a temporary variable
130 " template invocation in this case, you should save target_name to a\n" 133 outside of any target definitions.
131 " temporary variable outside of any target definitions.\n" 134
132 "\n" 135 See "gn help template" for more examples.
133 " See \"gn help template\" for more examples.\n" 136
134 "\n" 137 Example
135 "Example\n" 138
136 "\n" 139 executable("doom_melon") {
137 " executable(\"doom_melon\") {\n" 140 print(target_name) # Prints "doom_melon".
138 " print(target_name) # Prints \"doom_melon\".\n" 141 }
139 " }\n" 142
140 "\n" 143 template("my_template") {
141 " template(\"my_template\") {\n" 144 print(target_name) # Prints "space_ray" when invoked below.
142 " print(target_name) # Prints \"space_ray\" when invoked below.\n" 145
143 "\n" 146 executable(target_name + "_impl") {
144 " executable(target_name + \"_impl\") {\n" 147 print(target_name) # Prints "space_ray_impl".
145 " print(target_name) # Prints \"space_ray_impl\".\n" 148 }
146 " }\n" 149 }
147 " }\n" 150
148 "\n" 151 my_template("space_ray") {
149 " my_template(\"space_ray\") {\n" 152 }
150 " }\n"; 153 )";
151 154
152 const char kTargetOs[] = "target_os"; 155 const char kTargetOs[] = "target_os";
153 const char kTargetOs_HelpShort[] = 156 const char kTargetOs_HelpShort[] =
154 "target_os: [string] The desired operating system for the build."; 157 "target_os: [string] The desired operating system for the build.";
155 const char kTargetOs_Help[] = 158 const char kTargetOs_Help[] =
156 "target_os: The desired operating system for the build.\n" 159 R"(target_os: The desired operating system for the build.
157 "\n" 160
158 " This value should be used to indicate the desired operating system\n" 161 This value should be used to indicate the desired operating system for the
159 " for the primary object(s) of the build. It will match the OS of\n" 162 primary object(s) of the build. It will match the OS of the default
160 " the default toolchain.\n" 163 toolchain.
161 "\n" 164
162 " In many cases, this is the same as \"host_os\", but in the case of\n" 165 In many cases, this is the same as "host_os", but in the case of
163 " cross-compiles, it may be different. This variable differs from\n" 166 cross-compiles, it may be different. This variable differs from "current_os"
164 " \"current_os\" in that it can be referenced from inside any\n" 167 in that it can be referenced from inside any toolchain and will always return
165 " toolchain and will always return the initial value.\n" 168 the initial value.
166 "\n" 169
167 " This should be set to the most specific value possible. So,\n" 170 This should be set to the most specific value possible. So, "android" or
168 " \"android\" or \"chromeos\" should be used instead of \"linux\"\n" 171 "chromeos" should be used instead of "linux" where applicable, even though
169 " where applicable, even though Android and ChromeOS are both Linux\n" 172 Android and ChromeOS are both Linux variants. This can mean that one needs to
170 " variants. This can mean that one needs to write\n" 173 write
171 "\n" 174
172 " if (target_os == \"android\" || target_os == \"linux\") {\n" 175 if (target_os == "android" || target_os == "linux") {
173 " # ...\n" 176 # ...
174 " }\n" 177 }
175 "\n" 178
176 " and so forth.\n" 179 and so forth.
177 "\n" 180
178 " This value is not used internally by GN for any purpose, so it\n" 181 This value is not used internally by GN for any purpose, so it may be set to
179 " may be set to whatever value is needed for the build.\n" 182 whatever value is needed for the build. GN defaults this value to the empty
180 " GN defaults this value to the empty string (\"\") and the\n" 183 string ("") and the configuration files should set it to an appropriate value
181 " configuration files should set it to an appropriate value\n" 184 (e.g., setting it to the value of "host_os") if it is not set via the command
182 " (e.g., setting it to the value of \"host_os\") if it is not\n" 185 line or in the args.gn file.
183 " set via the command line or in the args.gn file.\n" 186
184 "\n" 187 Possible values
185 " Where practical, use one of the following list of common values:\n" 188
186 "\n" 189 - "android"
187 "Possible values:\n" 190 - "chromeos"
188 " - \"android\"\n" 191 - "ios"
189 " - \"chromeos\"\n" 192 - "linux"
190 " - \"ios\"\n" 193 - "nacl"
191 " - \"linux\"\n" 194 - "mac"
192 " - \"nacl\"\n" 195 - "win"
193 " - \"mac\"\n" 196 )";
194 " - \"win\"\n";
195 197
196 const char kCurrentCpu[] = "current_cpu"; 198 const char kCurrentCpu[] = "current_cpu";
197 const char kCurrentCpu_HelpShort[] = 199 const char kCurrentCpu_HelpShort[] =
198 "current_cpu: [string] The processor architecture of the current " 200 "current_cpu: [string] The processor architecture of the current "
199 "toolchain."; 201 "toolchain.";
200 const char kCurrentCpu_Help[] = 202 const char kCurrentCpu_Help[] =
201 "current_cpu: The processor architecture of the current toolchain.\n" 203 R"(current_cpu: The processor architecture of the current toolchain.
202 "\n" 204
203 " The build configuration usually sets this value based on the value\n" 205 The build configuration usually sets this value based on the value of
204 " of \"host_cpu\" (see \"gn help host_cpu\") and then threads\n" 206 "host_cpu" (see "gn help host_cpu") and then threads this through the
205 " this through the toolchain definitions to ensure that it always\n" 207 toolchain definitions to ensure that it always reflects the appropriate
206 " reflects the appropriate value.\n" 208 value.
207 "\n" 209
208 " This value is not used internally by GN for any purpose. It is\n" 210 This value is not used internally by GN for any purpose. It is set it to the
209 " set it to the empty string (\"\") by default but is declared so\n" 211 empty string ("") by default but is declared so that it can be overridden on
210 " that it can be overridden on the command line if so desired.\n" 212 the command line if so desired.
211 "\n" 213
212 " See \"gn help target_cpu\" for a list of common values returned.\n"; 214 See "gn help target_cpu" for a list of common values returned.)";
213 215
214 const char kCurrentOs[] = "current_os"; 216 const char kCurrentOs[] = "current_os";
215 const char kCurrentOs_HelpShort[] = 217 const char kCurrentOs_HelpShort[] =
216 "current_os: [string] The operating system of the current toolchain."; 218 "current_os: [string] The operating system of the current toolchain.";
217 const char kCurrentOs_Help[] = 219 const char kCurrentOs_Help[] =
218 "current_os: The operating system of the current toolchain.\n" 220 R"(current_os: The operating system of the current toolchain.
219 "\n" 221
220 " The build configuration usually sets this value based on the value\n" 222 The build configuration usually sets this value based on the value of
221 " of \"target_os\" (see \"gn help target_os\"), and then threads this\n" 223 "target_os" (see "gn help target_os"), and then threads this through the
222 " through the toolchain definitions to ensure that it always reflects\n" 224 toolchain definitions to ensure that it always reflects the appropriate
223 " the appropriate value.\n" 225 value.
224 "\n" 226
225 " This value is not used internally by GN for any purpose. It is\n" 227 This value is not used internally by GN for any purpose. It is set it to the
226 " set it to the empty string (\"\") by default but is declared so\n" 228 empty string ("") by default but is declared so that it can be overridden on
227 " that it can be overridden on the command line if so desired.\n" 229 the command line if so desired.
228 "\n" 230
229 " See \"gn help target_os\" for a list of common values returned.\n"; 231 See "gn help target_os" for a list of common values returned.
232 )";
230 233
231 const char kCurrentToolchain[] = "current_toolchain"; 234 const char kCurrentToolchain[] = "current_toolchain";
232 const char kCurrentToolchain_HelpShort[] = 235 const char kCurrentToolchain_HelpShort[] =
233 "current_toolchain: [string] Label of the current toolchain."; 236 "current_toolchain: [string] Label of the current toolchain.";
234 const char kCurrentToolchain_Help[] = 237 const char kCurrentToolchain_Help[] =
235 "current_toolchain: Label of the current toolchain.\n" 238 R"(current_toolchain: Label of the current toolchain.
236 "\n" 239
237 " A fully-qualified label representing the current toolchain. You can\n" 240 A fully-qualified label representing the current toolchain. You can use this
238 " use this to make toolchain-related decisions in the build. See also\n" 241 to make toolchain-related decisions in the build. See also
239 " \"default_toolchain\".\n" 242 "default_toolchain".
240 "\n" 243
241 "Example\n" 244 Example
242 "\n" 245
243 " if (current_toolchain == \"//build:64_bit_toolchain\") {\n" 246 if (current_toolchain == "//build:64_bit_toolchain") {
244 " executable(\"output_thats_64_bit_only\") {\n" 247 executable("output_thats_64_bit_only") {
245 " ...\n"; 248 ...
249 )";
246 250
247 const char kDefaultToolchain[] = "default_toolchain"; 251 const char kDefaultToolchain[] = "default_toolchain";
248 const char kDefaultToolchain_HelpShort[] = 252 const char kDefaultToolchain_HelpShort[] =
249 "default_toolchain: [string] Label of the default toolchain."; 253 "default_toolchain: [string] Label of the default toolchain.";
250 const char kDefaultToolchain_Help[] = 254 const char kDefaultToolchain_Help[] =
251 "default_toolchain: [string] Label of the default toolchain.\n" 255 R"(default_toolchain: [string] Label of the default toolchain.
252 "\n" 256
253 " A fully-qualified label representing the default toolchain, which may\n" 257 A fully-qualified label representing the default toolchain, which may not
254 " not necessarily be the current one (see \"current_toolchain\").\n"; 258 necessarily be the current one (see "current_toolchain").
259 )";
255 260
256 const char kPythonPath[] = "python_path"; 261 const char kPythonPath[] = "python_path";
257 const char kPythonPath_HelpShort[] = 262 const char kPythonPath_HelpShort[] =
258 "python_path: [string] Absolute path of Python."; 263 "python_path: [string] Absolute path of Python.";
259 const char kPythonPath_Help[] = 264 const char kPythonPath_Help[] =
260 "python_path: Absolute path of Python.\n" 265 R"(python_path: Absolute path of Python.
261 "\n" 266
262 " Normally used in toolchain definitions if running some command\n" 267 Normally used in toolchain definitions if running some command requires
263 " requires Python. You will normally not need this when invoking scripts\n" 268 Python. You will normally not need this when invoking scripts since GN
264 " since GN automatically finds it for you.\n"; 269 automatically finds it for you.
270 )";
265 271
266 const char kRootBuildDir[] = "root_build_dir"; 272 const char kRootBuildDir[] = "root_build_dir";
267 const char kRootBuildDir_HelpShort[] = 273 const char kRootBuildDir_HelpShort[] =
268 "root_build_dir: [string] Directory where build commands are run."; 274 "root_build_dir: [string] Directory where build commands are run.";
269 const char kRootBuildDir_Help[] = 275 const char kRootBuildDir_Help[] =
270 "root_build_dir: [string] Directory where build commands are run.\n" 276 R"(root_build_dir: [string] Directory where build commands are run.
271 "\n" 277
272 " This is the root build output directory which will be the current\n" 278 This is the root build output directory which will be the current directory
273 " directory when executing all compilers and scripts.\n" 279 when executing all compilers and scripts.
274 "\n" 280
275 " Most often this is used with rebase_path (see \"gn help rebase_path\")\n" 281 Most often this is used with rebase_path (see "gn help rebase_path") to
276 " to convert arguments to be relative to a script's current directory.\n"; 282 convert arguments to be relative to a script's current directory.
283 )";
277 284
278 const char kRootGenDir[] = "root_gen_dir"; 285 const char kRootGenDir[] = "root_gen_dir";
279 const char kRootGenDir_HelpShort[] = 286 const char kRootGenDir_HelpShort[] =
280 "root_gen_dir: [string] Directory for the toolchain's generated files."; 287 "root_gen_dir: [string] Directory for the toolchain's generated files.";
281 const char kRootGenDir_Help[] = 288 const char kRootGenDir_Help[] =
282 "root_gen_dir: Directory for the toolchain's generated files.\n" 289 R"(root_gen_dir: Directory for the toolchain's generated files.
283 "\n" 290
284 " Absolute path to the root of the generated output directory tree for\n" 291 Absolute path to the root of the generated output directory tree for the
285 " the current toolchain. An example would be \"//out/Debug/gen\" for the\n" 292 current toolchain. An example would be "//out/Debug/gen" for the default
286 " default toolchain, or \"//out/Debug/arm/gen\" for the \"arm\"\n" 293 toolchain, or "//out/Debug/arm/gen" for the "arm" toolchain.
287 " toolchain.\n" 294
288 "\n" 295 This is primarily useful for setting up include paths for generated files. If
289 " This is primarily useful for setting up include paths for generated\n" 296 you are passing this to a script, you will want to pass it through
290 " files. If you are passing this to a script, you will want to pass it\n" 297 rebase_path() (see "gn help rebase_path") to convert it to be relative to the
291 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 298 build directory.
292 " to be relative to the build directory.\n" 299
293 "\n" 300 See also "target_gen_dir" which is usually a better location for generated
294 " See also \"target_gen_dir\" which is usually a better location for\n" 301 files. It will be inside the root generated dir.
295 " generated files. It will be inside the root generated dir.\n"; 302 )";
296 303
297 const char kRootOutDir[] = "root_out_dir"; 304 const char kRootOutDir[] = "root_out_dir";
298 const char kRootOutDir_HelpShort[] = 305 const char kRootOutDir_HelpShort[] =
299 "root_out_dir: [string] Root directory for toolchain output files."; 306 "root_out_dir: [string] Root directory for toolchain output files.";
300 const char kRootOutDir_Help[] = 307 const char kRootOutDir_Help[] =
301 "root_out_dir: [string] Root directory for toolchain output files.\n" 308 R"(root_out_dir: [string] Root directory for toolchain output files.
302 "\n" 309
303 " Absolute path to the root of the output directory tree for the current\n" 310 Absolute path to the root of the output directory tree for the current
304 " toolchain. It will not have a trailing slash.\n" 311 toolchain. It will not have a trailing slash.
305 "\n" 312
306 " For the default toolchain this will be the same as the root_build_dir.\n" 313 For the default toolchain this will be the same as the root_build_dir. An
307 " An example would be \"//out/Debug\" for the default toolchain, or\n" 314 example would be "//out/Debug" for the default toolchain, or
308 " \"//out/Debug/arm\" for the \"arm\" toolchain.\n" 315 "//out/Debug/arm" for the "arm" toolchain.
309 "\n" 316
310 " This is primarily useful for setting up script calls. If you are\n" 317 This is primarily useful for setting up script calls. If you are passing this
311 " passing this to a script, you will want to pass it through\n" 318 to a script, you will want to pass it through rebase_path() (see "gn help
312 " rebase_path() (see \"gn help rebase_path\") to convert it\n" 319 rebase_path") to convert it to be relative to the build directory.
313 " to be relative to the build directory.\n" 320
314 "\n" 321 See also "target_out_dir" which is usually a better location for output
315 " See also \"target_out_dir\" which is usually a better location for\n" 322 files. It will be inside the root output dir.
316 " output files. It will be inside the root output dir.\n" 323
317 "\n" 324 Example
318 "Example\n" 325
319 "\n" 326 action("myscript") {
320 " action(\"myscript\") {\n" 327 # Pass the output dir to the script.
321 " # Pass the output dir to the script.\n" 328 args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
322 " args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n" 329 }
323 " }\n"; 330 )";
324 331
325 const char kTargetGenDir[] = "target_gen_dir"; 332 const char kTargetGenDir[] = "target_gen_dir";
326 const char kTargetGenDir_HelpShort[] = 333 const char kTargetGenDir_HelpShort[] =
327 "target_gen_dir: [string] Directory for a target's generated files."; 334 "target_gen_dir: [string] Directory for a target's generated files.";
328 const char kTargetGenDir_Help[] = 335 const char kTargetGenDir_Help[] =
329 "target_gen_dir: Directory for a target's generated files.\n" 336 R"(target_gen_dir: Directory for a target's generated files.
330 "\n" 337
331 " Absolute path to the target's generated file directory. This will be\n" 338 Absolute path to the target's generated file directory. This will be the
332 " the \"root_gen_dir\" followed by the relative path to the current\n" 339 "root_gen_dir" followed by the relative path to the current build file. If
333 " build file. If your file is in \"//tools/doom_melon\" then\n" 340 your file is in "//tools/doom_melon" then target_gen_dir would be
334 " target_gen_dir would be \"//out/Debug/gen/tools/doom_melon\". It will\n" 341 "//out/Debug/gen/tools/doom_melon". It will not have a trailing slash.
335 " not have a trailing slash.\n" 342
336 "\n" 343 This is primarily useful for setting up include paths for generated files. If
337 " This is primarily useful for setting up include paths for generated\n" 344 you are passing this to a script, you will want to pass it through
338 " files. If you are passing this to a script, you will want to pass it\n" 345 rebase_path() (see "gn help rebase_path") to convert it to be relative to the
339 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 346 build directory.
340 " to be relative to the build directory.\n" 347
341 "\n" 348 See also "gn help root_gen_dir".
342 " See also \"gn help root_gen_dir\".\n" 349
343 "\n" 350 Example
344 "Example\n" 351
345 "\n" 352 action("myscript") {
346 " action(\"myscript\") {\n" 353 # Pass the generated output dir to the script.
347 " # Pass the generated output dir to the script.\n" 354 args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]"
348 " args = [ \"-o\", rebase_path(target_gen_dir, root_build_dir) ]" 355 }
349 "\n" 356 )";
350 " }\n";
351 357
352 const char kTargetOutDir[] = "target_out_dir"; 358 const char kTargetOutDir[] = "target_out_dir";
353 const char kTargetOutDir_HelpShort[] = 359 const char kTargetOutDir_HelpShort[] =
354 "target_out_dir: [string] Directory for target output files."; 360 "target_out_dir: [string] Directory for target output files.";
355 const char kTargetOutDir_Help[] = 361 const char kTargetOutDir_Help[] =
356 "target_out_dir: [string] Directory for target output files.\n" 362 R"(target_out_dir: [string] Directory for target output files.
357 "\n" 363
358 " Absolute path to the target's generated file directory. If your\n" 364 Absolute path to the target's generated file directory. If your current
359 " current target is in \"//tools/doom_melon\" then this value might be\n" 365 target is in "//tools/doom_melon" then this value might be
360 " \"//out/Debug/obj/tools/doom_melon\". It will not have a trailing\n" 366 "//out/Debug/obj/tools/doom_melon". It will not have a trailing slash.
361 " slash.\n" 367
362 "\n" 368 This is primarily useful for setting up arguments for calling scripts. If you
363 " This is primarily useful for setting up arguments for calling\n" 369 are passing this to a script, you will want to pass it through rebase_path()
364 " scripts. If you are passing this to a script, you will want to pass it\n" 370 (see "gn help rebase_path") to convert it to be relative to the build
365 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 371 directory.
366 " to be relative to the build directory.\n" 372
367 "\n" 373 See also "gn help root_out_dir".
368 " See also \"gn help root_out_dir\".\n" 374
369 "\n" 375 Example
370 "Example\n" 376
371 "\n" 377 action("myscript") {
372 " action(\"myscript\") {\n" 378 # Pass the output dir to the script.
373 " # Pass the output dir to the script.\n" 379 args = [ "-o", rebase_path(target_out_dir, root_build_dir) ]"
374 " args = [ \"-o\", rebase_path(target_out_dir, root_build_dir) ]" 380
375 "\n" 381 }
376 " }\n"; 382 )";
377 383
378 // Target variables ------------------------------------------------------------ 384 // Target variables ------------------------------------------------------------
379 385
380 #define COMMON_ORDERING_HELP \ 386 #define COMMON_ORDERING_HELP \
381 "\n" \ 387 "\n" \
382 "Ordering of flags and values\n" \ 388 "Ordering of flags and values\n" \
383 "\n" \ 389 "\n" \
384 " 1. Those set on the current target (not in a config).\n" \ 390 " 1. Those set on the current target (not in a config).\n" \
385 " 2. Those set on the \"configs\" on the target in order that the\n" \ 391 " 2. Those set on the \"configs\" on the target in order that the\n" \
386 " configs appear in the list.\n" \ 392 " configs appear in the list.\n" \
387 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \ 393 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \
388 " that the configs appear in the list.\n" \ 394 " that the configs appear in the list.\n" \
389 " 4. Those set on the \"public_configs\" on the target in order that\n" \ 395 " 4. Those set on the \"public_configs\" on the target in order that\n" \
390 " those configs appear in the list.\n" \ 396 " those configs appear in the list.\n" \
391 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \ 397 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \
392 " the \"deps\" list. This is done recursively. If a config appears\n" \ 398 " the \"deps\" list. This is done recursively. If a config appears\n" \
393 " more than once, only the first occurance will be used.\n" \ 399 " more than once, only the first occurance will be used.\n" \
394 " 6. public_configs pulled from dependencies, in the order of the\n" \ 400 " 6. public_configs pulled from dependencies, in the order of the\n" \
395 " \"deps\" list. If a dependency is public, they will be applied\n" \ 401 " \"deps\" list. If a dependency is public, they will be applied\n" \
396 " recursively.\n" 402 " recursively.\n"
397 403
398 const char kAllDependentConfigs[] = "all_dependent_configs"; 404 const char kAllDependentConfigs[] = "all_dependent_configs";
399 const char kAllDependentConfigs_HelpShort[] = 405 const char kAllDependentConfigs_HelpShort[] =
400 "all_dependent_configs: [label list] Configs to be forced on dependents."; 406 "all_dependent_configs: [label list] Configs to be forced on dependents.";
401 const char kAllDependentConfigs_Help[] = 407 const char kAllDependentConfigs_Help[] =
402 "all_dependent_configs: Configs to be forced on dependents.\n" 408 R"(all_dependent_configs: Configs to be forced on dependents.
403 "\n" 409
404 " A list of config labels.\n" 410 A list of config labels.
405 "\n" 411
406 " All targets depending on this one, and recursively, all targets\n" 412 All targets depending on this one, and recursively, all targets depending on
407 " depending on those, will have the configs listed in this variable\n" 413 those, will have the configs listed in this variable added to them. These
408 " added to them. These configs will also apply to the current target.\n" 414 configs will also apply to the current target.
409 "\n" 415
410 " This addition happens in a second phase once a target and all of its\n" 416 This addition happens in a second phase once a target and all of its
411 " dependencies have been resolved. Therefore, a target will not see\n" 417 dependencies have been resolved. Therefore, a target will not see these
412 " these force-added configs in their \"configs\" variable while the\n" 418 force-added configs in their "configs" variable while the script is running,
413 " script is running, and then can not be removed. As a result, this\n" 419 and then can not be removed. As a result, this capability should generally
414 " capability should generally only be used to add defines and include\n" 420 only be used to add defines and include directories necessary to compile a
415 " directories necessary to compile a target's headers.\n" 421 target's headers.
416 "\n" 422
417 " See also \"public_configs\".\n" 423 See also "public_configs".
424 )"
418 COMMON_ORDERING_HELP; 425 COMMON_ORDERING_HELP;
419 426
420 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; 427 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from";
421 const char kAllowCircularIncludesFrom_HelpShort[] = 428 const char kAllowCircularIncludesFrom_HelpShort[] =
422 "allow_circular_includes_from: [label list] Permit includes from deps."; 429 "allow_circular_includes_from: [label list] Permit includes from deps.";
423 const char kAllowCircularIncludesFrom_Help[] = 430 const char kAllowCircularIncludesFrom_Help[] =
424 "allow_circular_includes_from: Permit includes from deps.\n" 431 R"(allow_circular_includes_from: Permit includes from deps.
425 "\n" 432
426 " A list of target labels. Must be a subset of the target's \"deps\".\n" 433 A list of target labels. Must be a subset of the target's "deps". These
427 " These targets will be permitted to include headers from the current\n" 434 targets will be permitted to include headers from the current target despite
428 " target despite the dependency going in the opposite direction.\n" 435 the dependency going in the opposite direction.
429 "\n" 436
430 " When you use this, both targets must be included in a final binary\n" 437 When you use this, both targets must be included in a final binary for it to
431 " for it to link. To keep linker errors from happening, it is good\n" 438 link. To keep linker errors from happening, it is good practice to have all
432 " practice to have all external dependencies depend only on one of\n" 439 external dependencies depend only on one of the two targets, and to set the
433 " the two targets, and to set the visibility on the other to enforce\n" 440 visibility on the other to enforce this. Thus the targets will always be
434 " this. Thus the targets will always be linked together in any output.\n" 441 linked together in any output.
435 "\n" 442
436 "Details\n" 443 Details
437 "\n" 444
438 " Normally, for a file in target A to include a file from target B,\n" 445 Normally, for a file in target A to include a file from target B, A must list
439 " A must list B as a dependency. This invariant is enforced by the\n" 446 B as a dependency. This invariant is enforced by the "gn check" command (and
440 " \"gn check\" command (and the --check flag to \"gn gen\" -- see\n" 447 the --check flag to "gn gen" -- see "gn help check").
441 " \"gn help check\").\n" 448
442 "\n" 449 Sometimes, two targets might be the same unit for linking purposes (two
443 " Sometimes, two targets might be the same unit for linking purposes\n" 450 source sets or static libraries that would always be linked together in a
444 " (two source sets or static libraries that would always be linked\n" 451 final executable or shared library) and they each include headers from the
445 " together in a final executable or shared library) and they each\n" 452 other: you want A to be able to include B's headers, and B to include A's
446 " include headers from the other: you want A to be able to include B's\n" 453 headers. This is not an ideal situation but is sometimes unavoidable.
447 " headers, and B to include A's headers. This is not an ideal situation\n" 454
448 " but is sometimes unavoidable.\n" 455 This list, if specified, lists which of the dependencies of the current
449 "\n" 456 target can include header files from the current target. That is, if A
450 " This list, if specified, lists which of the dependencies of the\n" 457 depends on B, B can only include headers from A if it is in A's
451 " current target can include header files from the current target.\n" 458 allow_circular_includes_from list. Normally includes must follow the
452 " That is, if A depends on B, B can only include headers from A if it is\n" 459 direction of dependencies, this flag allows them to go in the opposite
453 " in A's allow_circular_includes_from list. Normally includes must\n" 460 direction.
454 " follow the direction of dependencies, this flag allows them to go\n" 461
455 " in the opposite direction.\n" 462 Danger
456 "\n" 463
457 "Danger\n" 464 In the above example, A's headers are likely to include headers from A's
458 "\n" 465 dependencies. Those dependencies may have public_configs that apply flags,
459 " In the above example, A's headers are likely to include headers from\n" 466 defines, and include paths that make those headers work properly.
460 " A's dependencies. Those dependencies may have public_configs that\n" 467
461 " apply flags, defines, and include paths that make those headers work\n" 468 With allow_circular_includes_from, B can include A's headers, and
462 " properly.\n" 469 transitively from A's dependencies, without having the dependencies that
463 "\n" 470 would bring in the public_configs those headers need. The result may be
464 " With allow_circular_includes_from, B can include A's headers, and\n" 471 errors or inconsistent builds.
465 " transitively from A's dependencies, without having the dependencies\n" 472
466 " that would bring in the public_configs those headers need. The result\n" 473 So when you use allow_circular_includes_from, make sure that any compiler
467 " may be errors or inconsistent builds.\n" 474 settings, flags, and include directories are the same between both targets
468 "\n" 475 (consider putting such things in a shared config they can both reference).
469 " So when you use allow_circular_includes_from, make sure that any\n" 476 Make sure the dependencies are also the same (you might consider a group to
470 " compiler settings, flags, and include directories are the same between\n" 477 collect such dependencies they both depend on).
471 " both targets (consider putting such things in a shared config they can\n" 478
472 " both reference). Make sure the dependencies are also the same (you\n" 479 Example
473 " might consider a group to collect such dependencies they both\n" 480
474 " depend on).\n" 481 source_set("a") {
475 "\n" 482 deps = [ ":b", ":a_b_shared_deps" ]
476 "Example\n" 483 allow_circular_includes_from = [ ":b" ]
477 "\n" 484 ...
478 " source_set(\"a\") {\n" 485 }
479 " deps = [ \":b\", \":a_b_shared_deps\" ]\n" 486
480 " allow_circular_includes_from = [ \":b\" ]\n" 487 source_set("b") {
481 " ...\n" 488 deps = [ ":a_b_shared_deps" ]
482 " }\n" 489 # Sources here can include headers from a despite lack of deps.
483 "\n" 490 ...
484 " source_set(\"b\") {\n" 491 }
485 " deps = [ \":a_b_shared_deps\" ]\n" 492
486 " # Sources here can include headers from a despite lack of deps.\n" 493 group("a_b_shared_deps") {
487 " ...\n" 494 public_deps = [ ":c" ]
488 " }\n" 495 }
489 "\n" 496 )";
490 " group(\"a_b_shared_deps\") {\n"
491 " public_deps = [ \":c\" ]\n"
492 " }\n";
493 497
494 const char kArflags[] = "arflags"; 498 const char kArflags[] = "arflags";
495 const char kArflags_HelpShort[] = 499 const char kArflags_HelpShort[] =
496 "arflags: [string list] Arguments passed to static_library archiver."; 500 "arflags: [string list] Arguments passed to static_library archiver.";
497 const char kArflags_Help[] = 501 const char kArflags_Help[] =
498 "arflags: Arguments passed to static_library archiver.\n" 502 R"(arflags: Arguments passed to static_library archiver.
499 "\n" 503
500 " A list of flags passed to the archive/lib command that creates static\n" 504 A list of flags passed to the archive/lib command that creates static
501 " libraries.\n" 505 libraries.
502 "\n" 506
503 " arflags are NOT pushed to dependents, so applying arflags to source\n" 507 arflags are NOT pushed to dependents, so applying arflags to source sets or
504 " sets or any other target type will be a no-op. As with ldflags,\n" 508 any other target type will be a no-op. As with ldflags, you could put the
505 " you could put the arflags in a config and set that as a public or\n" 509 arflags in a config and set that as a public or "all dependent" config, but
506 " \"all dependent\" config, but that will likely not be what you want.\n" 510 that will likely not be what you want. If you have a chain of static
507 " If you have a chain of static libraries dependent on each other,\n" 511 libraries dependent on each other, this can cause the flags to propagate up
508 " this can cause the flags to propagate up to other static libraries.\n" 512 to other static libraries. Due to the nature of how arflags are typically
509 " Due to the nature of how arflags are typically used, you will normally\n" 513 used, you will normally want to apply them directly on static_library targets
510 " want to apply them directly on static_library targets themselves.\n" 514 themselves.
515 )"
511 COMMON_ORDERING_HELP; 516 COMMON_ORDERING_HELP;
512 517
513 const char kArgs[] = "args"; 518 const char kArgs[] = "args";
514 const char kArgs_HelpShort[] = 519 const char kArgs_HelpShort[] =
515 "args: [string list] Arguments passed to an action."; 520 "args: [string list] Arguments passed to an action.";
516 const char kArgs_Help[] = 521 const char kArgs_Help[] =
517 "args: Arguments passed to an action.\n" 522 R"(args: Arguments passed to an action.
518 "\n" 523
519 " For action and action_foreach targets, args is the list of arguments\n" 524 For action and action_foreach targets, args is the list of arguments to pass
520 " to pass to the script. Typically you would use source expansion (see\n" 525 to the script. Typically you would use source expansion (see "gn help
521 " \"gn help source_expansion\") to insert the source file names.\n" 526 source_expansion") to insert the source file names.
522 "\n" 527
523 " See also \"gn help action\" and \"gn help action_foreach\".\n"; 528 See also "gn help action" and "gn help action_foreach".
529 )";
524 530
525 const char kAssertNoDeps[] = "assert_no_deps"; 531 const char kAssertNoDeps[] = "assert_no_deps";
526 const char kAssertNoDeps_HelpShort[] = 532 const char kAssertNoDeps_HelpShort[] =
527 "assert_no_deps: [label pattern list] Ensure no deps on these targets."; 533 "assert_no_deps: [label pattern list] Ensure no deps on these targets.";
528 const char kAssertNoDeps_Help[] = 534 const char kAssertNoDeps_Help[] =
529 "assert_no_deps: Ensure no deps on these targets.\n" 535 R"(assert_no_deps: Ensure no deps on these targets.
530 "\n" 536
531 " A list of label patterns.\n" 537 A list of label patterns.
532 "\n" 538
533 " This list is a list of patterns that must not match any of the\n" 539 This list is a list of patterns that must not match any of the transitive
534 " transitive dependencies of the target. These include all public,\n" 540 dependencies of the target. These include all public, private, and data
535 " private, and data dependencies, and cross shared library boundaries.\n" 541 dependencies, and cross shared library boundaries. This allows you to express
536 " This allows you to express that undesirable code isn't accidentally\n" 542 that undesirable code isn't accidentally added to downstream dependencies in
537 " added to downstream dependencies in a way that might otherwise be\n" 543 a way that might otherwise be difficult to notice.
538 " difficult to notice.\n" 544
539 "\n" 545 Checking does not cross executable boundaries. If a target depends on an
540 " Checking does not cross executable boundaries. If a target depends on\n" 546 executable, it's assumed that the executable is a tool that is producing part
541 " an executable, it's assumed that the executable is a tool that is\n" 547 of the build rather than something that is linked and distributed. This
542 " producing part of the build rather than something that is linked and\n" 548 allows assert_no_deps to express what is distributed in the final target
543 " distributed. This allows assert_no_deps to express what is distributed\n" 549 rather than depend on the internal build steps (which may include
544 " in the final target rather than depend on the internal build steps\n" 550 non-distributable code).
545 " (which may include non-distributable code).\n" 551
546 "\n" 552 See "gn help label_pattern" for the format of the entries in the list. These
547 " See \"gn help label_pattern\" for the format of the entries in the\n" 553 patterns allow blacklisting individual targets or whole directory
548 " list. These patterns allow blacklisting individual targets or whole\n" 554 hierarchies.
549 " directory hierarchies.\n" 555
550 "\n" 556 Sometimes it is desirable to enforce that many targets have no dependencies
551 " Sometimes it is desirable to enforce that many targets have no\n" 557 on a target or set of targets. One efficient way to express this is to create
552 " dependencies on a target or set of targets. One efficient way to\n" 558 a group with the assert_no_deps rule on it, and make that group depend on all
553 " express this is to create a group with the assert_no_deps rule on\n" 559 targets you want to apply that assertion to.
554 " it, and make that group depend on all targets you want to apply that\n" 560
555 " assertion to.\n" 561 Example
556 "\n" 562
557 "Example\n" 563 executable("doom_melon") {
558 "\n" 564 deps = [ "//foo:bar" ]
559 " executable(\"doom_melon\") {\n" 565 ...
560 " deps = [ \"//foo:bar\" ]\n" 566 assert_no_deps = [
561 " ...\n" 567 "//evil/*", # Don't link any code from the evil directory.
562 " assert_no_deps = [\n" 568 "//foo:test_support", # This target is also disallowed.
563 " \"//evil/*\", # Don't link any code from the evil directory.\n" 569 ]
564 " \"//foo:test_support\", # This target is also disallowed.\n" 570 }
565 " ]\n" 571 )";
566 " }\n";
567 572
568 const char kBundleRootDir[] = "bundle_root_dir"; 573 const char kBundleRootDir[] = "bundle_root_dir";
569 const char kBundleRootDir_HelpShort[] = 574 const char kBundleRootDir_HelpShort[] =
570 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle."; 575 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.";
571 const char kBundleRootDir_Help[] = 576 const char kBundleRootDir_Help[] =
572 "bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.\n" 577 R"(bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.
573 "\n" 578
574 " A string corresponding to a path in root_build_dir.\n" 579 A string corresponding to a path in root_build_dir.
575 "\n" 580
576 " This string is used by the \"create_bundle\" target to expand the\n" 581 This string is used by the "create_bundle" target to expand the
577 " {{bundle_root_dir}} of the \"bundle_data\" target it depends on.\n" 582 {{bundle_root_dir}} of the "bundle_data" target it depends on. This must
578 " This must correspond to a path under root_build_dir.\n" 583 correspond to a path under root_build_dir.
579 "\n" 584
580 "Example\n" 585 Example
581 "\n" 586
582 " bundle_data(\"info_plist\") {\n" 587 bundle_data("info_plist") {
583 " sources = [ \"Info.plist\" ]\n" 588 sources = [ "Info.plist" ]
584 " outputs = [ \"{{bundle_root_dir}}/Info.plist\" ]\n" 589 outputs = [ "{{bundle_root_dir}}/Info.plist" ]
585 " }\n" 590 }
586 "\n" 591
587 " create_bundle(\"doom_melon.app\") {\n" 592 create_bundle("doom_melon.app") {
588 " deps = [ \":info_plist\" ]\n" 593 deps = [ ":info_plist" ]
589 " bundle_root_dir = root_build_dir + \"/doom_melon.app/Contents\"\n" 594 bundle_root_dir = root_build_dir + "/doom_melon.app/Contents"
590 " bundle_resources_dir = bundle_root_dir + \"/Resources\"\n" 595 bundle_resources_dir = bundle_root_dir + "/Resources"
591 " bundle_executable_dir = bundle_root_dir + \"/MacOS\"\n" 596 bundle_executable_dir = bundle_root_dir + "/MacOS"
592 " bundle_plugins_dir = bundle_root_dir + \"/PlugIns\"\n" 597 bundle_plugins_dir = bundle_root_dir + "/PlugIns"
593 " }\n"; 598 }
599 )";
594 600
595 const char kBundleResourcesDir[] = "bundle_resources_dir"; 601 const char kBundleResourcesDir[] = "bundle_resources_dir";
596 const char kBundleResourcesDir_HelpShort[] = 602 const char kBundleResourcesDir_HelpShort[] =
597 "bundle_resources_dir: " 603 "bundle_resources_dir: "
598 "Expansion of {{bundle_resources_dir}} in create_bundle."; 604 "Expansion of {{bundle_resources_dir}} in create_bundle.";
599 const char kBundleResourcesDir_Help[] = 605 const char kBundleResourcesDir_Help[] =
600 "bundle_resources_dir: " 606 R"(bundle_resources_dir: Expansion of {{bundle_resources_dir}} in
601 "Expansion of {{bundle_resources_dir}} in create_bundle.\n" 607 create_bundle.
602 "\n" 608
603 " A string corresponding to a path in $root_build_dir.\n" 609 A string corresponding to a path in $root_build_dir.
604 "\n" 610
605 " This string is used by the \"create_bundle\" target to expand the\n" 611 This string is used by the "create_bundle" target to expand the
606 " {{bundle_resources_dir}} of the \"bundle_data\" target it depends on.\n" 612 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must
607 " This must correspond to a path under \"bundle_root_dir\".\n" 613 correspond to a path under "bundle_root_dir".
608 "\n" 614
609 " See \"gn help bundle_root_dir\" for examples.\n"; 615 See "gn help bundle_root_dir" for examples.
616 )";
610 617
611 const char kBundleDepsFilter[] = "bundle_deps_filter"; 618 const char kBundleDepsFilter[] = "bundle_deps_filter";
612 const char kBundleDepsFilter_HelpShort[] = 619 const char kBundleDepsFilter_HelpShort[] =
613 "bundle_deps_filter: [label list] A list of labels that are filtered out."; 620 "bundle_deps_filter: [label list] A list of labels that are filtered out.";
614 const char kBundleDepsFilter_Help[] = 621 const char kBundleDepsFilter_Help[] =
615 "bundle_deps_filter: [label list] A list of labels that are filtered out.\n" 622 R"(bundle_deps_filter: [label list] A list of labels that are filtered out.
616 "\n" 623
617 " A list of target labels.\n" 624 A list of target labels.
618 "\n" 625
619 " This list contains target label patterns that should be filtered out\n" 626 This list contains target label patterns that should be filtered out when
620 " when creating the bundle. Any target matching one of those label will\n" 627 creating the bundle. Any target matching one of those label will be removed
621 " be removed from the dependencies of the create_bundle target.\n" 628 from the dependencies of the create_bundle target.
622 "\n" 629
623 " This is mostly useful when creating application extension bundle as\n" 630 This is mostly useful when creating application extension bundle as the
624 " the application extension has access to runtime resources from the\n" 631 application extension has access to runtime resources from the application
625 " application bundle and thus do not require a second copy.\n" 632 bundle and thus do not require a second copy.
626 "\n" 633
627 " See \"gn help create_bundle\" for more information.\n" 634 See "gn help create_bundle" for more information.
628 "\n" 635
629 "Example\n" 636 Example
630 "\n" 637
631 " create_bundle(\"today_extension\") {\n" 638 create_bundle("today_extension") {
632 " deps = [\n" 639 deps = [
633 " \"//base\"\n" 640 "//base"
634 " ]\n" 641 ]
635 " bundle_root_dir = \"$root_out_dir/today_extension.appex\"\n" 642 bundle_root_dir = "$root_out_dir/today_extension.appex"
636 " bundle_deps_filter = [\n" 643 bundle_deps_filter = [
637 " # The extension uses //base but does not use any function calling\n" 644 # The extension uses //base but does not use any function calling into
638 " # into third_party/icu and thus does not need the icudtl.dat file.\n" 645 # third_party/icu and thus does not need the icudtl.dat file.
639 " \"//third_party/icu:icudata\",\n" 646 "//third_party/icu:icudata",
640 " ]\n" 647 ]
641 " }\n"; 648 }
649 )";
642 650
643 const char kBundleExecutableDir[] = "bundle_executable_dir"; 651 const char kBundleExecutableDir[] = "bundle_executable_dir";
644 const char kBundleExecutableDir_HelpShort[] = 652 const char kBundleExecutableDir_HelpShort[] =
645 "bundle_executable_dir: " 653 "bundle_executable_dir: "
646 "Expansion of {{bundle_executable_dir}} in create_bundle"; 654 "Expansion of {{bundle_executable_dir}} in create_bundle";
647 const char kBundleExecutableDir_Help[] = 655 const char kBundleExecutableDir_Help[] =
648 "bundle_executable_dir: " 656 R"(bundle_executable_dir: Expansion of {{bundle_executable_dir}} in
649 "Expansion of {{bundle_executable_dir}} in create_bundle.\n" 657 create_bundle.
650 "\n" 658
651 " A string corresponding to a path in $root_build_dir.\n" 659 A string corresponding to a path in $root_build_dir.
652 "\n" 660
653 " This string is used by the \"create_bundle\" target to expand the\n" 661 This string is used by the "create_bundle" target to expand the
654 " {{bundle_executable_dir}} of the \"bundle_data\" target it depends on.\n" 662 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This
655 " This must correspond to a path under \"bundle_root_dir\".\n" 663 must correspond to a path under "bundle_root_dir".
656 "\n" 664
657 " See \"gn help bundle_root_dir\" for examples.\n"; 665 See "gn help bundle_root_dir" for examples.
666 )";
658 667
659 const char kBundlePlugInsDir[] = "bundle_plugins_dir"; 668 const char kBundlePlugInsDir[] = "bundle_plugins_dir";
660 const char kBundlePlugInsDir_HelpShort[] = 669 const char kBundlePlugInsDir_HelpShort[] =
661 "bundle_plugins_dir: " 670 "bundle_plugins_dir: "
662 "Expansion of {{bundle_plugins_dir}} in create_bundle."; 671 "Expansion of {{bundle_plugins_dir}} in create_bundle.";
663 const char kBundlePlugInsDir_Help[] = 672 const char kBundlePlugInsDir_Help[] =
664 "bundle_plugins_dir: " 673 R"(bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle.
665 "Expansion of {{bundle_plugins_dir}} in create_bundle.\n" 674
666 "\n" 675 A string corresponding to a path in $root_build_dir.
667 " A string corresponding to a path in $root_build_dir.\n" 676
668 "\n" 677 This string is used by the "create_bundle" target to expand the
669 " This string is used by the \"create_bundle\" target to expand the\n" 678 {{bundle_plugins_dir}} of the "bundle_data" target it depends on. This must
670 " {{bundle_plugins_dir}} of the \"bundle_data\" target it depends on.\n" 679 correspond to a path under "bundle_root_dir".
671 " This must correspond to a path under \"bundle_root_dir\".\n" 680
672 "\n" 681 See "gn help bundle_root_dir" for examples.
673 " See \"gn help bundle_root_dir\" for examples.\n"; 682 )";
674 683
675 const char kCflags[] = "cflags"; 684 const char kCflags[] = "cflags";
676 const char kCflags_HelpShort[] = 685 const char kCflags_HelpShort[] =
677 "cflags: [string list] Flags passed to all C compiler variants."; 686 "cflags: [string list] Flags passed to all C compiler variants.";
678 const char kCommonCflagsHelp[] = 687 const char kCommonCflagsHelp[] =
679 "cflags*: Flags passed to the C compiler.\n" 688 R"(cflags*: Flags passed to the C compiler.
680 "\n" 689
681 " A list of strings.\n" 690 A list of strings.
682 "\n" 691
683 " \"cflags\" are passed to all invocations of the C, C++, Objective C,\n" 692 "cflags" are passed to all invocations of the C, C++, Objective C, and
684 " and Objective C++ compilers.\n" 693 Objective C++ compilers.
685 "\n" 694
686 " To target one of these variants individually, use \"cflags_c\",\n" 695 To target one of these variants individually, use "cflags_c", "cflags_cc",
687 " \"cflags_cc\", \"cflags_objc\", and \"cflags_objcc\",\n" 696 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
688 " respectively. These variant-specific versions of cflags* will be\n" 697 versions of cflags* will be appended on the compiler command line after
689 " appended on the compiler command line after \"cflags\".\n" 698 "cflags".
690 "\n" 699
691 " See also \"asmflags\" for flags for assembly-language files.\n" 700 See also "asmflags" for flags for assembly-language files.
701 )"
692 COMMON_ORDERING_HELP; 702 COMMON_ORDERING_HELP;
693 const char* kCflags_Help = kCommonCflagsHelp; 703 const char* kCflags_Help = kCommonCflagsHelp;
694 704
695 const char kAsmflags[] = "asmflags"; 705 const char kAsmflags[] = "asmflags";
696 const char kAsmflags_HelpShort[] = 706 const char kAsmflags_HelpShort[] =
697 "asmflags: [string list] Flags passed to the assembler."; 707 "asmflags: [string list] Flags passed to the assembler.";
698 const char* kAsmflags_Help = 708 const char* kAsmflags_Help =
699 "asmflags: Flags passed to the assembler.\n" 709 R"(asmflags: Flags passed to the assembler.
700 "\n" 710
701 " A list of strings.\n" 711 A list of strings.
702 "\n" 712
703 " \"asmflags\" are passed to any invocation of a tool that takes an\n" 713 "asmflags" are passed to any invocation of a tool that takes an .asm or .S
704 " .asm or .S file as input.\n" 714 file as input.
715 )"
705 COMMON_ORDERING_HELP; 716 COMMON_ORDERING_HELP;
706 717
707 const char kCflagsC[] = "cflags_c"; 718 const char kCflagsC[] = "cflags_c";
708 const char kCflagsC_HelpShort[] = 719 const char kCflagsC_HelpShort[] =
709 "cflags_c: [string list] Flags passed to the C compiler."; 720 "cflags_c: [string list] Flags passed to the C compiler.";
710 const char* kCflagsC_Help = kCommonCflagsHelp; 721 const char* kCflagsC_Help = kCommonCflagsHelp;
711 722
712 const char kCflagsCC[] = "cflags_cc"; 723 const char kCflagsCC[] = "cflags_cc";
713 const char kCflagsCC_HelpShort[] = 724 const char kCflagsCC_HelpShort[] =
714 "cflags_cc: [string list] Flags passed to the C++ compiler."; 725 "cflags_cc: [string list] Flags passed to the C++ compiler.";
715 const char* kCflagsCC_Help = kCommonCflagsHelp; 726 const char* kCflagsCC_Help = kCommonCflagsHelp;
716 727
717 const char kCflagsObjC[] = "cflags_objc"; 728 const char kCflagsObjC[] = "cflags_objc";
718 const char kCflagsObjC_HelpShort[] = 729 const char kCflagsObjC_HelpShort[] =
719 "cflags_objc: [string list] Flags passed to the Objective C compiler."; 730 "cflags_objc: [string list] Flags passed to the Objective C compiler.";
720 const char* kCflagsObjC_Help = kCommonCflagsHelp; 731 const char* kCflagsObjC_Help = kCommonCflagsHelp;
721 732
722 const char kCflagsObjCC[] = "cflags_objcc"; 733 const char kCflagsObjCC[] = "cflags_objcc";
723 const char kCflagsObjCC_HelpShort[] = 734 const char kCflagsObjCC_HelpShort[] =
724 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler."; 735 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler.";
725 const char* kCflagsObjCC_Help = kCommonCflagsHelp; 736 const char* kCflagsObjCC_Help = kCommonCflagsHelp;
726 737
727 const char kCheckIncludes[] = "check_includes"; 738 const char kCheckIncludes[] = "check_includes";
728 const char kCheckIncludes_HelpShort[] = 739 const char kCheckIncludes_HelpShort[] =
729 "check_includes: [boolean] Controls whether a target's files are checked."; 740 "check_includes: [boolean] Controls whether a target's files are checked.";
730 const char kCheckIncludes_Help[] = 741 const char kCheckIncludes_Help[] =
731 "check_includes: [boolean] Controls whether a target's files are checked.\n" 742 R"(check_includes: [boolean] Controls whether a target's files are checked.
732 "\n" 743
733 " When true (the default), the \"gn check\" command (as well as\n" 744 When true (the default), the "gn check" command (as well as "gn gen" with the
734 " \"gn gen\" with the --check flag) will check this target's sources\n" 745 --check flag) will check this target's sources and headers for proper
735 " and headers for proper dependencies.\n" 746 dependencies.
736 "\n" 747
737 " When false, the files in this target will be skipped by default.\n" 748 When false, the files in this target will be skipped by default. This does
738 " This does not affect other targets that depend on the current target,\n" 749 not affect other targets that depend on the current target, it just skips
739 " it just skips checking the includes of the current target's files.\n" 750 checking the includes of the current target's files.
740 "\n" 751
741 " If there are a few conditionally included headers that trip up\n" 752 If there are a few conditionally included headers that trip up checking, you
742 " checking, you can exclude headers individually by annotating them with\n" 753 can exclude headers individually by annotating them with "nogncheck" (see "gn
743 " \"nogncheck\" (see \"gn help nogncheck\").\n" 754 help nogncheck").
744 "\n" 755
745 " The topic \"gn help check\" has general information on how checking\n" 756 The topic "gn help check" has general information on how checking works and
746 " works and advice on how to pass a check in problematic cases.\n" 757 advice on how to pass a check in problematic cases.
747 "\n" 758
748 "Example\n" 759 Example
749 "\n" 760
750 " source_set(\"busted_includes\") {\n" 761 source_set("busted_includes") {
751 " # This target's includes are messed up, exclude it from checking.\n" 762 # This target's includes are messed up, exclude it from checking.
752 " check_includes = false\n" 763 check_includes = false
753 " ...\n" 764 ...
754 " }\n"; 765 }
766 )";
755 767
756 const char kCodeSigningArgs[] = "code_signing_args"; 768 const char kCodeSigningArgs[] = "code_signing_args";
757 const char kCodeSigningArgs_HelpShort[] = 769 const char kCodeSigningArgs_HelpShort[] =
758 "code_signing_args: [string list] Arguments passed to code signing script."; 770 "code_signing_args: [string list] Arguments passed to code signing script.";
759 const char kCodeSigningArgs_Help[] = 771 const char kCodeSigningArgs_Help[] =
760 "code_signing_args: [string list] Arguments passed to code signing " 772 R"(code_signing_args: [string list] Arguments passed to code signing script.
761 "script.\n" 773
762 "\n" 774 For create_bundle targets, code_signing_args is the list of arguments to pass
763 " For create_bundle targets, code_signing_args is the list of arguments\n" 775 to the code signing script. Typically you would use source expansion (see "gn
764 " to pass to the code signing script. Typically you would use source\n" 776 help source_expansion") to insert the source file names.
765 " expansion (see \"gn help source_expansion\") to insert the source file\n" 777
766 " names.\n" 778 See also "gn help create_bundle".
767 "\n" 779 )";
768 " See also \"gn help create_bundle\".\n";
769 780
770 const char kCodeSigningScript[] = "code_signing_script"; 781 const char kCodeSigningScript[] = "code_signing_script";
771 const char kCodeSigningScript_HelpShort[] = 782 const char kCodeSigningScript_HelpShort[] =
772 "code_signing_script: [file name] Script for code signing."; 783 "code_signing_script: [file name] Script for code signing.";
773 const char kCodeSigningScript_Help[] = 784 const char kCodeSigningScript_Help[] =
774 "code_signing_script: [file name] Script for code signing." 785 R"(code_signing_script: [file name] Script for code signing."
775 "\n" 786
776 " An absolute or buildfile-relative file name of a Python script to run\n" 787 An absolute or buildfile-relative file name of a Python script to run for a
777 " for a create_bundle target to perform code signing step.\n" 788 create_bundle target to perform code signing step.
778 "\n" 789
779 " See also \"gn help create_bundle\".\n"; 790 See also "gn help create_bundle".
791 )";
780 792
781 const char kCodeSigningSources[] = "code_signing_sources"; 793 const char kCodeSigningSources[] = "code_signing_sources";
782 const char kCodeSigningSources_HelpShort[] = 794 const char kCodeSigningSources_HelpShort[] =
783 "code_signing_sources: [file list] Sources for code signing step."; 795 "code_signing_sources: [file list] Sources for code signing step.";
784 const char kCodeSigningSources_Help[] = 796 const char kCodeSigningSources_Help[] =
785 "code_signing_sources: [file list] Sources for code signing step.\n" 797 R"(code_signing_sources: [file list] Sources for code signing step.
786 "\n" 798
787 " A list of files used as input for code signing script step of a\n" 799 A list of files used as input for code signing script step of a create_bundle
788 " create_bundle target. Non-absolute paths will be resolved relative to\n" 800 target. Non-absolute paths will be resolved relative to the current build
789 " the current build file.\n" 801 file.
790 "\n" 802
791 " See also \"gn help create_bundle\".\n"; 803 See also "gn help create_bundle".
804 )";
792 805
793 const char kCodeSigningOutputs[] = "code_signing_outputs"; 806 const char kCodeSigningOutputs[] = "code_signing_outputs";
794 const char kCodeSigningOutputs_HelpShort[] = 807 const char kCodeSigningOutputs_HelpShort[] =
795 "code_signing_outputs: [file list] Output files for code signing step."; 808 "code_signing_outputs: [file list] Output files for code signing step.";
796 const char kCodeSigningOutputs_Help[] = 809 const char kCodeSigningOutputs_Help[] =
797 "code_signing_outputs: [file list] Output files for code signing step.\n" 810 R"(code_signing_outputs: [file list] Output files for code signing step.
798 "\n" 811
799 " Outputs from the code signing step of a create_bundle target. Must\n" 812 Outputs from the code signing step of a create_bundle target. Must refer to
800 " refer to files in the build directory.\n" 813 files in the build directory.
801 "\n" 814
802 " See also \"gn help create_bundle\".\n"; 815 See also "gn help create_bundle".
816 )";
803 817
804 const char kCompleteStaticLib[] = "complete_static_lib"; 818 const char kCompleteStaticLib[] = "complete_static_lib";
805 const char kCompleteStaticLib_HelpShort[] = 819 const char kCompleteStaticLib_HelpShort[] =
806 "complete_static_lib: [boolean] Links all deps into a static library."; 820 "complete_static_lib: [boolean] Links all deps into a static library.";
807 const char kCompleteStaticLib_Help[] = 821 const char kCompleteStaticLib_Help[] =
808 "complete_static_lib: [boolean] Links all deps into a static library.\n" 822 R"(complete_static_lib: [boolean] Links all deps into a static library.
809 "\n" 823
810 " A static library normally doesn't include code from dependencies, but\n" 824 A static library normally doesn't include code from dependencies, but instead
811 " instead forwards the static libraries and source sets in its deps up\n" 825 forwards the static libraries and source sets in its deps up the dependency
812 " the dependency chain until a linkable target (an executable or shared\n" 826 chain until a linkable target (an executable or shared library) is reached.
813 " library) is reached. The final linkable target only links each static\n" 827 The final linkable target only links each static library once, even if it
814 " library once, even if it appears more than once in its dependency\n" 828 appears more than once in its dependency graph.
815 " graph.\n" 829
816 "\n" 830 In some cases the static library might be the final desired output. For
817 " In some cases the static library might be the final desired output.\n" 831 example, you may be producing a static library for distribution to third
818 " For example, you may be producing a static library for distribution to\n" 832 parties. In this case, the static library should include code for all
819 " third parties. In this case, the static library should include code\n" 833 dependencies in one complete package. However, complete static libraries
820 " for all dependencies in one complete package. However, complete static\n" 834 themselves are never linked into other complete static libraries. All
821 " libraries themselves are never linked into other complete static\n" 835 complete static libraries are for distribution and linking them in would
822 " libraries. All complete static libraries are for distribution and\n" 836 cause code duplication in this case. If the static library is not for
823 " linking them in would cause code duplication in this case. If the\n" 837 distribution, it should not be complete.
824 " static library is not for distribution, it should not be complete.\n" 838
825 "\n" 839 GN treats non-complete static libraries as source sets when they are linked
826 " GN treats non-complete static libraries as source sets when they are\n" 840 into complete static libraries. This is done because some tools like AR do
827 " linked into complete static libraries. This is done because some tools\n" 841 not handle dependent static libraries properly. This makes it easier to write
828 " like AR do not handle dependent static libraries properly. This makes\n" 842 "alink" rules.
829 " it easier to write \"alink\" rules.\n" 843
830 "\n" 844 In rare cases it makes sense to list a header in more than one target if it
831 " In rare cases it makes sense to list a header in more than one\n" 845 could be considered conceptually a member of both. libraries.
832 " target if it could be considered conceptually a member of both.\n" 846
833 " libraries.\n" 847 Example
834 "\n" 848
835 "Example\n" 849 static_library("foo") {
836 "\n" 850 complete_static_lib = true
837 " static_library(\"foo\") {\n" 851 deps = [ "bar" ]
838 " complete_static_lib = true\n" 852 }
839 " deps = [ \"bar\" ]\n" 853 )";
840 " }\n";
841 854
842 const char kConfigs[] = "configs"; 855 const char kConfigs[] = "configs";
843 const char kConfigs_HelpShort[] = 856 const char kConfigs_HelpShort[] =
844 "configs: [label list] Configs applying to this target or config."; 857 "configs: [label list] Configs applying to this target or config.";
845 const char kConfigs_Help[] = 858 const char kConfigs_Help[] =
846 "configs: Configs applying to this target or config.\n" 859 R"(configs: Configs applying to this target or config.
847 "\n" 860
848 " A list of config labels.\n" 861 A list of config labels.
849 "\n" 862
850 "Configs on a target\n" 863 Configs on a target
851 "\n" 864
852 " When used on a target, the include_dirs, defines, etc. in each config\n" 865 When used on a target, the include_dirs, defines, etc. in each config are
853 " are appended in the order they appear to the compile command for each\n" 866 appended in the order they appear to the compile command for each file in the
854 " file in the target. They will appear after the include_dirs, defines,\n" 867 target. They will appear after the include_dirs, defines, etc. that the
855 " etc. that the target sets directly.\n" 868 target sets directly.
856 "\n" 869
857 " Since configs apply after the values set on a target, directly setting\n" 870 Since configs apply after the values set on a target, directly setting a
858 " a compiler flag will prepend it to the command line. If you want to\n" 871 compiler flag will prepend it to the command line. If you want to append a
859 " append a flag instead, you can put that flag in a one-off config and\n" 872 flag instead, you can put that flag in a one-off config and append that
860 " append that config to the target's configs list.\n" 873 config to the target's configs list.
861 "\n" 874
862 " The build configuration script will generally set up the default\n" 875 The build configuration script will generally set up the default configs
863 " configs applying to a given target type (see \"set_defaults\").\n" 876 applying to a given target type (see "set_defaults"). When a target is being
864 " When a target is being defined, it can add to or remove from this\n" 877 defined, it can add to or remove from this list.
865 " list.\n" 878
866 "\n" 879 Configs on a config
867 "Configs on a config\n" 880
868 "\n" 881 It is possible to create composite configs by specifying configs on a config.
869 " It is possible to create composite configs by specifying configs on a\n" 882 One might do this to forward values, or to factor out blocks of settings from
870 " config. One might do this to forward values, or to factor out blocks\n" 883 very large configs into more manageable named chunks.
871 " of settings from very large configs into more manageable named chunks.\n" 884
872 "\n" 885 In this case, the composite config is expanded to be the concatenation of its
873 " In this case, the composite config is expanded to be the concatenation\n" 886 own values, and in order, the values from its sub-configs *before* anything
874 " of its own values, and in order, the values from its sub-configs\n" 887 else happens. This has some ramifications:
875 " *before* anything else happens. This has some ramifications:\n" 888
876 "\n" 889 - A target has no visibility into a config's sub-configs. Target code only
877 " - A target has no visibility into a config's sub-configs. Target\n" 890 sees the name of the composite config. It can't remove sub-configs or opt
878 " code only sees the name of the composite config. It can't remove\n" 891 in to only parts of it. The composite config may not even be defined
879 " sub-configs or opt in to only parts of it. The composite config may\n" 892 before the target is.
880 " not even be defined before the target is.\n" 893
881 "\n" 894 - You can get duplication of values if a config is listed twice, say, on a
882 " - You can get duplication of values if a config is listed twice, say,\n" 895 target and in a sub-config that also applies. In other cases, the configs
883 " on a target and in a sub-config that also applies. In other cases,\n" 896 applying to a target are de-duped. It's expected that if a config is
884 " the configs applying to a target are de-duped. It's expected that\n" 897 listed as a sub-config that it is only used in that context. (Note that
885 " if a config is listed as a sub-config that it is only used in that\n" 898 it's possible to fix this and de-dupe, but it's not normally relevant and
886 " context. (Note that it's possible to fix this and de-dupe, but it's\n" 899 complicates the implementation.)
887 " not normally relevant and complicates the implementation.)\n" 900 )"
888 COMMON_ORDERING_HELP 901 COMMON_ORDERING_HELP
889 "\n" 902 R"(
890 "Example\n" 903 Example
891 "\n" 904
892 " # Configs on a target.\n" 905 # Configs on a target.
893 " source_set(\"foo\") {\n" 906 source_set("foo") {
894 " # Don't use the default RTTI config that BUILDCONFIG applied to us.\n" 907 # Don't use the default RTTI config that BUILDCONFIG applied to us.
895 " configs -= [ \"//build:no_rtti\" ]\n" 908 configs -= [ "//build:no_rtti" ]
896 "\n" 909
897 " # Add some of our own settings.\n" 910 # Add some of our own settings.
898 " configs += [ \":mysettings\" ]\n" 911 configs += [ ":mysettings" ]
899 " }\n" 912 }
900 "\n" 913
901 " # Create a default_optimization config that forwards to one of a set\n" 914 # Create a default_optimization config that forwards to one of a set of more
902 " # of more specialized configs depending on build flags. This pattern\n" 915 # specialized configs depending on build flags. This pattern is useful
903 " # is useful because it allows a target to opt in to either a default\n" 916 # because it allows a target to opt in to either a default set, or a more
904 " # set, or a more specific set, while avoid duplicating the settings in\n" 917 # specific set, while avoid duplicating the settings in two places.
905 " # two places.\n" 918 config("super_optimization") {
906 " config(\"super_optimization\") {\n" 919 cflags = [ ... ]
907 " cflags = [ ... ]\n" 920 }
908 " }\n" 921 config("default_optimization") {
909 " config(\"default_optimization\") {\n" 922 if (optimize_everything) {
910 " if (optimize_everything) {\n" 923 configs = [ ":super_optimization" ]
911 " configs = [ \":super_optimization\" ]\n" 924 } else {
912 " } else {\n" 925 configs = [ ":no_optimization" ]
913 " configs = [ \":no_optimization\" ]\n" 926 }
914 " }\n" 927 }
915 " }\n"; 928 )";
916 929
917 const char kConsole[] = "console"; 930 const char kConsole[] = "console";
918 const char kConsole_HelpShort[] = 931 const char kConsole_HelpShort[] =
919 "console: [boolean] Run this action in the console pool."; 932 "console: [boolean] Run this action in the console pool.";
920 const char kConsole_Help[] = 933 const char kConsole_Help[] =
921 "console: Run this action in the console pool.\n" 934 R"(console: Run this action in the console pool.
922 "\n" 935
923 " Boolean. Defaults to false.\n" 936 Boolean. Defaults to false.
924 "\n" 937
925 " Actions marked \"console = true\" will be run in the built-in ninja\n" 938 Actions marked "console = true" will be run in the built-in ninja "console"
926 " \"console\" pool. They will have access to real stdin and stdout, and\n" 939 pool. They will have access to real stdin and stdout, and output will not be
927 " output will not be buffered by ninja. This can be useful for\n" 940 buffered by ninja. This can be useful for long-running actions with progress
928 " long-running actions with progress logs, or actions that require user \n" 941 logs, or actions that require user input.
929 " input.\n" 942
930 "\n" 943 Only one console pool target can run at any one time in Ninja. Refer to the
931 " Only one console pool target can run at any one time in Ninja. Refer\n" 944 Ninja documentation on the console pool for more info.
932 " to the Ninja documentation on the console pool for more info.\n" 945
933 "\n" 946 Example
934 "Example\n" 947
935 "\n" 948 action("long_action_with_progress_logs") {
936 " action(\"long_action_with_progress_logs\") {\n" 949 console = true
937 " console = true\n" 950 }
938 " }\n"; 951 )";
939 952
940 const char kData[] = "data"; 953 const char kData[] = "data";
941 const char kData_HelpShort[] = 954 const char kData_HelpShort[] =
942 "data: [file list] Runtime data file dependencies."; 955 "data: [file list] Runtime data file dependencies.";
943 const char kData_Help[] = 956 const char kData_Help[] =
944 "data: Runtime data file dependencies.\n" 957 R"(data: Runtime data file dependencies.
945 "\n" 958
946 " Lists files or directories required to run the given target. These are\n" 959 Lists files or directories required to run the given target. These are
947 " typically data files or directories of data files. The paths are\n" 960 typically data files or directories of data files. The paths are interpreted
948 " interpreted as being relative to the current build file. Since these\n" 961 as being relative to the current build file. Since these are runtime
949 " are runtime dependencies, they do not affect which targets are built\n" 962 dependencies, they do not affect which targets are built or when. To declare
950 " or when. To declare input files to a script, use \"inputs\".\n" 963 input files to a script, use "inputs".
951 "\n" 964
952 " Appearing in the \"data\" section does not imply any special handling\n" 965 Appearing in the "data" section does not imply any special handling such as
953 " such as copying them to the output directory. This is just used for\n" 966 copying them to the output directory. This is just used for declaring runtime
954 " declaring runtime dependencies. Runtime dependencies can be queried\n" 967 dependencies. Runtime dependencies can be queried using the "runtime_deps"
955 " using the \"runtime_deps\" category of \"gn desc\" or written during\n" 968 category of "gn desc" or written during build generation via
956 " build generation via \"--runtime-deps-list-file\".\n" 969 "--runtime-deps-list-file".
957 "\n" 970
958 " GN doesn't require data files to exist at build-time. So actions that\n" 971 GN doesn't require data files to exist at build-time. So actions that produce
959 " produce files that are in turn runtime dependencies can list those\n" 972 files that are in turn runtime dependencies can list those generated files
960 " generated files both in the \"outputs\" list as well as the \"data\"\n" 973 both in the "outputs" list as well as the "data" list.
961 " list.\n" 974
962 "\n" 975 By convention, directories are listed with a trailing slash:
963 " By convention, directories are listed with a trailing slash:\n" 976 data = [ "test/data/" ]
964 " data = [ \"test/data/\" ]\n" 977 However, no verification is done on these so GN doesn't enforce this. The
965 " However, no verification is done on these so GN doesn't enforce this.\n" 978 paths are just rebased and passed along when requested.
966 " The paths are just rebased and passed along when requested.\n" 979
967 "\n" 980 Note: On iOS and OS X, create_bundle targets will not be recursed into when
968 " Note: On iOS and OS X, create_bundle targets will not be recursed\n" 981 gathering data. See "gn help create_bundle" for details.
969 " into when gathering data. See \"gn help create_bundle\" for details.\n" 982
970 "\n" 983 See "gn help runtime_deps" for how these are used.
971 " See \"gn help runtime_deps\" for how these are used.\n"; 984 )";
972 985
973 const char kDataDeps[] = "data_deps"; 986 const char kDataDeps[] = "data_deps";
974 const char kDataDeps_HelpShort[] = 987 const char kDataDeps_HelpShort[] =
975 "data_deps: [label list] Non-linked dependencies."; 988 "data_deps: [label list] Non-linked dependencies.";
976 const char kDataDeps_Help[] = 989 const char kDataDeps_Help[] =
977 "data_deps: Non-linked dependencies.\n" 990 R"(data_deps: Non-linked dependencies.
978 "\n" 991
979 " A list of target labels.\n" 992 A list of target labels.
980 "\n" 993
981 " Specifies dependencies of a target that are not actually linked into\n" 994 Specifies dependencies of a target that are not actually linked into the
982 " the current target. Such dependencies will be built and will be\n" 995 current target. Such dependencies will be built and will be available at
983 " available at runtime.\n" 996 runtime.
984 "\n" 997
985 " This is normally used for things like plugins or helper programs that\n" 998 This is normally used for things like plugins or helper programs that a
986 " a target needs at runtime.\n" 999 target needs at runtime.
987 "\n" 1000
988 " Note: On iOS and OS X, create_bundle targets will not be recursed\n" 1001 Note: On iOS and OS X, create_bundle targets will not be recursed into when
989 " into when gathering data_deps. See \"gn help create_bundle\" for\n" 1002 gathering data_deps. See "gn help create_bundle" for details.
990 " details.\n" 1003
991 "\n" 1004 See also "gn help deps" and "gn help data".
992 " See also \"gn help deps\" and \"gn help data\".\n" 1005
993 "\n" 1006 Example
994 "Example\n" 1007
995 "\n" 1008 executable("foo") {
996 " executable(\"foo\") {\n" 1009 deps = [ "//base" ]
997 " deps = [ \"//base\" ]\n" 1010 data_deps = [ "//plugins:my_runtime_plugin" ]
998 " data_deps = [ \"//plugins:my_runtime_plugin\" ]\n" 1011 }
999 " }\n"; 1012 )";
1000 1013
1001 const char kDefines[] = "defines"; 1014 const char kDefines[] = "defines";
1002 const char kDefines_HelpShort[] = 1015 const char kDefines_HelpShort[] =
1003 "defines: [string list] C preprocessor defines."; 1016 "defines: [string list] C preprocessor defines.";
1004 const char kDefines_Help[] = 1017 const char kDefines_Help[] =
1005 "defines: C preprocessor defines.\n" 1018 R"(defines: C preprocessor defines.
1006 "\n" 1019
1007 " A list of strings\n" 1020 A list of strings
1008 "\n" 1021
1009 " These strings will be passed to the C/C++ compiler as #defines. The\n" 1022 These strings will be passed to the C/C++ compiler as #defines. The strings
1010 " strings may or may not include an \"=\" to assign a value.\n" 1023 may or may not include an "=" to assign a value.
1024 )"
1011 COMMON_ORDERING_HELP 1025 COMMON_ORDERING_HELP
1012 "\n" 1026 R"(
1013 "Example\n" 1027 Example
1014 "\n" 1028
1015 " defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n"; 1029 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
1030 )";
1016 1031
1017 const char kDepfile[] = "depfile"; 1032 const char kDepfile[] = "depfile";
1018 const char kDepfile_HelpShort[] = 1033 const char kDepfile_HelpShort[] =
1019 "depfile: [string] File name for input dependencies for actions."; 1034 "depfile: [string] File name for input dependencies for actions.";
1020 const char kDepfile_Help[] = 1035 const char kDepfile_Help[] =
1021 "depfile: [string] File name for input dependencies for actions.\n" 1036 R"(depfile: [string] File name for input dependencies for actions.
1022 "\n" 1037
1023 " If nonempty, this string specifies that the current action or\n" 1038 If nonempty, this string specifies that the current action or action_foreach
1024 " action_foreach target will generate the given \".d\" file containing\n" 1039 target will generate the given ".d" file containing the dependencies of the
1025 " the dependencies of the input. Empty or unset means that the script\n" 1040 input. Empty or unset means that the script doesn't generate the files.
1026 " doesn't generate the files.\n" 1041
1027 "\n" 1042 A depfile should be used only when a target depends on files that are not
1028 " A depfile should be used only when a target depends on files that are\n" 1043 already specified by a target's inputs and sources. Likewise, depfiles should
1029 " not already specified by a target's inputs and sources. Likewise,\n" 1044 specify only those dependencies not already included in sources or inputs.
1030 " depfiles should specify only those dependencies not already included\n" 1045
1031 " in sources or inputs.\n" 1046 The .d file should go in the target output directory. If you have more than
1032 "\n" 1047 one source file that the script is being run over, you can use the output
1033 " The .d file should go in the target output directory. If you have more\n" 1048 file expansions described in "gn help action_foreach" to name the .d file
1034 " than one source file that the script is being run over, you can use\n" 1049 according to the input."
1035 " the output file expansions described in \"gn help action_foreach\" to\n" 1050
1036 " name the .d file according to the input." 1051 The format is that of a Makefile and all paths must be relative to the root
1037 "\n" 1052 build directory. Only one output may be listed and it must match the first
1038 " The format is that of a Makefile and all paths must be relative to the\n" 1053 output of the action.
1039 " root build directory. Only one output may be listed and it must match\n" 1054
1040 " the first output of the action.\n" 1055 Although depfiles are created by an action, they should not be listed in the
1041 "\n" 1056 action's "outputs" unless another target will use the file as an input.
1042 " Although depfiles are created by an action, they should not be listed\n" 1057
1043 " in the action's \"outputs\" unless another target will use the file as\n" 1058 Example
1044 " an input.\n" 1059
1045 "\n" 1060 action_foreach("myscript_target") {
1046 "Example\n" 1061 script = "myscript.py"
1047 "\n" 1062 sources = [ ... ]
1048 " action_foreach(\"myscript_target\") {\n" 1063
1049 " script = \"myscript.py\"\n" 1064 # Locate the depfile in the output directory named like the
1050 " sources = [ ... ]\n" 1065 # inputs but with a ".d" appended.
1051 "\n" 1066 depfile = "$relative_target_output_dir/{{source_name}}.d"
1052 " # Locate the depfile in the output directory named like the\n" 1067
1053 " # inputs but with a \".d\" appended.\n" 1068 # Say our script uses "-o <d file>" to indicate the depfile.
1054 " depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n" 1069 args = [ "{{source}}", "-o", depfile ]
1055 "\n" 1070 }
1056 " # Say our script uses \"-o <d file>\" to indicate the depfile.\n" 1071 )";
1057 " args = [ \"{{source}}\", \"-o\", depfile ]\n"
1058 " }\n";
1059 1072
1060 const char kDeps[] = "deps"; 1073 const char kDeps[] = "deps";
1061 const char kDeps_HelpShort[] = 1074 const char kDeps_HelpShort[] =
1062 "deps: [label list] Private linked dependencies."; 1075 "deps: [label list] Private linked dependencies.";
1063 const char kDeps_Help[] = 1076 const char kDeps_Help[] =
1064 "deps: Private linked dependencies.\n" 1077 R"(deps: Private linked dependencies.
1065 "\n" 1078
1066 " A list of target labels.\n" 1079 A list of target labels.
1067 "\n" 1080
1068 " Specifies private dependencies of a target. Private dependencies are\n" 1081 Specifies private dependencies of a target. Private dependencies are
1069 " propagated up the dependency tree and linked to dependant targets, but\n" 1082 propagated up the dependency tree and linked to dependant targets, but do not
1070 " do not grant the ability to include headers from the dependency.\n" 1083 grant the ability to include headers from the dependency. Public configs are
1071 " Public configs are not forwarded.\n" 1084 not forwarded.
1072 "\n" 1085
1073 "Details of dependency propagation\n" 1086 Details of dependency propagation
1074 "\n" 1087
1075 " Source sets, shared libraries, and non-complete static libraries\n" 1088 Source sets, shared libraries, and non-complete static libraries will be
1076 " will be propagated up the dependency tree across groups, non-complete\n" 1089 propagated up the dependency tree across groups, non-complete static
1077 " static libraries and source sets.\n" 1090 libraries and source sets.
1078 "\n" 1091
1079 " Executables, shared libraries, and complete static libraries will\n" 1092 Executables, shared libraries, and complete static libraries will link all
1080 " link all propagated targets and stop propagation. Actions and copy\n" 1093 propagated targets and stop propagation. Actions and copy steps also stop
1081 " steps also stop propagation, allowing them to take a library as an\n" 1094 propagation, allowing them to take a library as an input but not force
1082 " input but not force dependants to link to it.\n" 1095 dependants to link to it.
1083 "\n" 1096
1084 " Propagation of all_dependent_configs and public_configs happens\n" 1097 Propagation of all_dependent_configs and public_configs happens independently
1085 " independently of target type. all_dependent_configs are always\n" 1098 of target type. all_dependent_configs are always propagated across all types
1086 " propagated across all types of targets, and public_configs\n" 1099 of targets, and public_configs are always propagated across public deps of
1087 " are always propagated across public deps of all types of targets.\n" 1100 all types of targets.
1088 "\n" 1101
1089 " Data dependencies are propagated differently. See\n" 1102 Data dependencies are propagated differently. See "gn help data_deps" and
1090 " \"gn help data_deps\" and \"gn help runtime_deps\".\n" 1103 "gn help runtime_deps".
1091 "\n" 1104
1092 " See also \"public_deps\".\n"; 1105 See also "public_deps".
1106 )";
1093 1107
1094 const char kIncludeDirs[] = "include_dirs"; 1108 const char kIncludeDirs[] = "include_dirs";
1095 const char kIncludeDirs_HelpShort[] = 1109 const char kIncludeDirs_HelpShort[] =
1096 "include_dirs: [directory list] Additional include directories."; 1110 "include_dirs: [directory list] Additional include directories.";
1097 const char kIncludeDirs_Help[] = 1111 const char kIncludeDirs_Help[] =
1098 "include_dirs: Additional include directories.\n" 1112 R"(include_dirs: Additional include directories.
1099 "\n" 1113
1100 " A list of source directories.\n" 1114 A list of source directories.
1101 "\n" 1115
1102 " The directories in this list will be added to the include path for\n" 1116 The directories in this list will be added to the include path for the files
1103 " the files in the affected target.\n" 1117 in the affected target.
1118 )"
1104 COMMON_ORDERING_HELP 1119 COMMON_ORDERING_HELP
1105 "\n" 1120 R"(
1106 "Example\n" 1121 Example
1107 "\n" 1122
1108 " include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n"; 1123 include_dirs = [ "src/include", "//third_party/foo" ]
1124 )";
1109 1125
1110 const char kInputs[] = "inputs"; 1126 const char kInputs[] = "inputs";
1111 const char kInputs_HelpShort[] = 1127 const char kInputs_HelpShort[] =
1112 "inputs: [file list] Additional compile-time dependencies."; 1128 "inputs: [file list] Additional compile-time dependencies.";
1113 const char kInputs_Help[] = 1129 const char kInputs_Help[] =
1114 "inputs: Additional compile-time dependencies.\n" 1130 R"(inputs: Additional compile-time dependencies.
1115 "\n" 1131
1116 " Inputs are compile-time dependencies of the current target. This means\n" 1132 Inputs are compile-time dependencies of the current target. This means that
1117 " that all inputs must be available before compiling any of the sources\n" 1133 all inputs must be available before compiling any of the sources or executing
1118 " or executing any actions.\n" 1134 any actions.
1119 "\n" 1135
1120 " Inputs are typically only used for action and action_foreach targets.\n" 1136 Inputs are typically only used for action and action_foreach targets.
1121 "\n" 1137
1122 "Inputs for actions\n" 1138 Inputs for actions
1123 "\n" 1139
1124 " For action and action_foreach targets, inputs should be the inputs to\n" 1140 For action and action_foreach targets, inputs should be the inputs to script
1125 " script that don't vary. These should be all .py files that the script\n" 1141 that don't vary. These should be all .py files that the script uses via
1126 " uses via imports (the main script itself will be an implicit dependency" 1142 imports (the main script itself will be an implicit dependency of the action
1127 "\n" 1143 so need not be listed).
1128 " of the action so need not be listed).\n" 1144
1129 "\n" 1145 For action targets, inputs and sources are treated the same, but from a style
1130 " For action targets, inputs and sources are treated the same, but from\n" 1146 perspective, it's recommended to follow the same rule as action_foreach and
1131 " a style perspective, it's recommended to follow the same rule as\n" 1147 put helper files in the inputs, and the data used by the script (if any) in
1132 " action_foreach and put helper files in the inputs, and the data used\n" 1148 sources.
1133 " by the script (if any) in sources.\n" 1149
1134 "\n" 1150 Note that another way to declare input dependencies from an action is to have
1135 " Note that another way to declare input dependencies from an action\n" 1151 the action write a depfile (see "gn help depfile"). This allows the script to
1136 " is to have the action write a depfile (see \"gn help depfile\"). This\n" 1152 dynamically write input dependencies, that might not be known until actually
1137 " allows the script to dynamically write input dependencies, that might\n" 1153 executing the script. This is more efficient than doing processing while
1138 " not be known until actually executing the script. This is more\n" 1154 running GN to determine the inputs, and is easier to keep in-sync than
1139 " efficient than doing processing while running GN to determine the\n" 1155 hardcoding the list.
1140 " inputs, and is easier to keep in-sync than hardcoding the list.\n" 1156
1141 "\n" 1157 Script input gotchas
1142 "Script input gotchas\n" 1158
1143 "\n" 1159 It may be tempting to write a script that enumerates all files in a directory
1144 " It may be tempting to write a script that enumerates all files in a\n" 1160 as inputs. Don't do this! Even if you specify all the files in the inputs or
1145 " directory as inputs. Don't do this! Even if you specify all the files\n" 1161 sources in the GN target (or worse, enumerate the files in an exec_script
1146 " in the inputs or sources in the GN target (or worse, enumerate the\n" 1162 call when running GN, which will be slow), the dependencies will be broken.
1147 " files in an exec_script call when running GN, which will be slow), the\n" 1163
1148 " dependencies will be broken.\n" 1164 The problem happens if a file is ever removed because the inputs are not
1149 "\n" 1165 listed on the command line to the script. Because the script hasn't changed
1150 " The problem happens if a file is ever removed because the inputs are\n" 1166 and all inputs are up to date, the script will not re-run and you will get a
1151 " not listed on the command line to the script. Because the script\n" 1167 stale build. Instead, either list all inputs on the command line to the
1152 " hasn't changed and all inputs are up to date, the script will not\n" 1168 script, or if there are many, create a separate list file that the script
1153 " re-run and you will get a stale build. Instead, either list all\n" 1169 reads. As long as this file is listed in the inputs, the build will detect
1154 " inputs on the command line to the script, or if there are many, create\n" 1170 when it has changed in any way and the action will re-run.
1155 " a separate list file that the script reads. As long as this file is\n" 1171
1156 " listed in the inputs, the build will detect when it has changed in any\n" 1172 Inputs for binary targets
1157 " way and the action will re-run.\n" 1173
1158 "\n" 1174 Any input dependencies will be resolved before compiling any sources.
1159 "Inputs for binary targets\n" 1175 Normally, all actions that a target depends on will be run before any files
1160 "\n" 1176 in a target are compiled. So if you depend on generated headers, you do not
1161 " Any input dependencies will be resolved before compiling any sources.\n" 1177 typically need to list them in the inputs section.
1162 " Normally, all actions that a target depends on will be run before any\n" 1178
1163 " files in a target are compiled. So if you depend on generated headers,\n" 1179 Inputs for binary targets will be treated as implicit dependencies, meaning
1164 " you do not typically need to list them in the inputs section.\n" 1180 that changes in any of the inputs will force all sources in the target to be
1165 "\n" 1181 recompiled. If an input only applies to a subset of source files, you may
1166 " Inputs for binary targets will be treated as implicit dependencies,\n" 1182 want to split those into a separate target to avoid unnecessary recompiles.
1167 " meaning that changes in any of the inputs will force all sources in\n" 1183
1168 " the target to be recompiled. If an input only applies to a subset of\n" 1184 Example
1169 " source files, you may want to split those into a separate target to\n" 1185
1170 " avoid unnecessary recompiles.\n" 1186 action("myscript") {
1171 "\n" 1187 script = "domything.py"
1172 "Example\n" 1188 inputs = [ "input.data" ]
1173 "\n" 1189 }
1174 " action(\"myscript\") {\n" 1190 )";
1175 " script = \"domything.py\"\n"
1176 " inputs = [ \"input.data\" ]\n"
1177 " }\n";
1178 1191
1179 const char kLdflags[] = "ldflags"; 1192 const char kLdflags[] = "ldflags";
1180 const char kLdflags_HelpShort[] = 1193 const char kLdflags_HelpShort[] =
1181 "ldflags: [string list] Flags passed to the linker."; 1194 "ldflags: [string list] Flags passed to the linker.";
1182 const char kLdflags_Help[] = 1195 const char kLdflags_Help[] =
1183 "ldflags: Flags passed to the linker.\n" 1196 R"(ldflags: Flags passed to the linker.
1184 "\n" 1197
1185 " A list of strings.\n" 1198 A list of strings.
1186 "\n" 1199
1187 " These flags are passed on the command-line to the linker and generally\n" 1200 These flags are passed on the command-line to the linker and generally
1188 " specify various linking options. Most targets will not need these and\n" 1201 specify various linking options. Most targets will not need these and will
1189 " will use \"libs\" and \"lib_dirs\" instead.\n" 1202 use "libs" and "lib_dirs" instead.
1190 "\n" 1203
1191 " ldflags are NOT pushed to dependents, so applying ldflags to source\n" 1204 ldflags are NOT pushed to dependents, so applying ldflags to source sets or
1192 " sets or static libraries will be a no-op. If you want to apply ldflags\n" 1205 static libraries will be a no-op. If you want to apply ldflags to dependent
1193 " to dependent targets, put them in a config and set it in the\n" 1206 targets, put them in a config and set it in the all_dependent_configs or
1194 " all_dependent_configs or public_configs.\n" 1207 public_configs.
1208 )"
1195 COMMON_ORDERING_HELP; 1209 COMMON_ORDERING_HELP;
1196 1210
1197 #define COMMON_LIB_INHERITANCE_HELP \ 1211 #define COMMON_LIB_INHERITANCE_HELP \
1198 "\n" \ 1212 "\n" \
1199 " libs and lib_dirs work differently than other flags in two respects.\n" \ 1213 " libs and lib_dirs work differently than other flags in two respects.\n" \
1200 " First, then are inherited across static library boundaries until a\n" \ 1214 " First, then are inherited across static library boundaries until a\n" \
1201 " shared library or executable target is reached. Second, they are\n" \ 1215 " shared library or executable target is reached. Second, they are\n" \
1202 " uniquified so each one is only passed once (the first instance of it\n" \ 1216 " uniquified so each one is only passed once (the first instance of it\n" \
1203 " will be the one used).\n" 1217 " will be the one used).\n"
1204 1218
1205 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \ 1219 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \
1206 "\n" \ 1220 "\n" \
1207 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \ 1221 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \
1208 " dependencies (as described above) are applied last assuming they\n" \ 1222 " dependencies (as described above) are applied last assuming they\n" \
1209 " are not already in the list.\n" 1223 " are not already in the list.\n"
1210 1224
1211 const char kLibDirs[] = "lib_dirs"; 1225 const char kLibDirs[] = "lib_dirs";
1212 const char kLibDirs_HelpShort[] = 1226 const char kLibDirs_HelpShort[] =
1213 "lib_dirs: [directory list] Additional library directories."; 1227 "lib_dirs: [directory list] Additional library directories.";
1214 const char kLibDirs_Help[] = 1228 const char kLibDirs_Help[] =
1215 "lib_dirs: Additional library directories.\n" 1229 R"(lib_dirs: Additional library directories.
1216 "\n" 1230
1217 " A list of directories.\n" 1231 A list of directories.
1218 "\n" 1232
1219 " Specifies additional directories passed to the linker for searching\n" 1233 Specifies additional directories passed to the linker for searching for the
1220 " for the required libraries. If an item is not an absolute path, it\n" 1234 required libraries. If an item is not an absolute path, it will be treated as
1221 " will be treated as being relative to the current build file.\n" 1235 being relative to the current build file.
1236 )"
1222 COMMON_LIB_INHERITANCE_HELP 1237 COMMON_LIB_INHERITANCE_HELP
1223 COMMON_ORDERING_HELP 1238 COMMON_ORDERING_HELP
1224 LIBS_AND_LIB_DIRS_ORDERING_HELP 1239 LIBS_AND_LIB_DIRS_ORDERING_HELP
1225 "\n" 1240 R"(
1226 "Example\n" 1241 Example
1227 "\n" 1242
1228 " lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n"; 1243 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
1244 )";
1229 1245
1230 const char kLibs[] = "libs"; 1246 const char kLibs[] = "libs";
1231 const char kLibs_HelpShort[] = 1247 const char kLibs_HelpShort[] =
1232 "libs: [string list] Additional libraries to link."; 1248 "libs: [string list] Additional libraries to link.";
1233 const char kLibs_Help[] = 1249 const char kLibs_Help[] =
1234 "libs: Additional libraries to link.\n" 1250 R"(libs: Additional libraries to link.
1235 "\n" 1251
1236 " A list of library names or library paths.\n" 1252 A list of library names or library paths.
1237 "\n" 1253
1238 " These libraries will be linked into the final binary (executable or\n" 1254 These libraries will be linked into the final binary (executable or shared
1239 " shared library) containing the current target.\n" 1255 library) containing the current target.
1256 )"
1240 COMMON_LIB_INHERITANCE_HELP 1257 COMMON_LIB_INHERITANCE_HELP
1241 "\n" 1258 R"(
1242 "Types of libs\n" 1259 Types of libs
1243 "\n" 1260
1244 " There are several different things that can be expressed in libs:\n" 1261 There are several different things that can be expressed in libs:
1245 "\n" 1262
1246 " File paths\n" 1263 File paths
1247 " Values containing '/' will be treated as references to files in\n" 1264 Values containing '/' will be treated as references to files in the
1248 " the checkout. They will be rebased to be relative to the build\n" 1265 checkout. They will be rebased to be relative to the build directory and
1249 " directory and specified in the \"libs\" for linker tools. This\n" 1266 specified in the "libs" for linker tools. This facility should be used
1250 " facility should be used for libraries that are checked in to the\n" 1267 for libraries that are checked in to the version control. For libraries
1251 " version control. For libraries that are generated by the build,\n" 1268 that are generated by the build, use normal GN deps to link them.
1252 " use normal GN deps to link them.\n" 1269
1253 "\n" 1270 System libraries
1254 " System libraries\n" 1271 Values not containing '/' will be treated as system library names. These
1255 " Values not containing '/' will be treated as system library names.\n" 1272 will be passed unmodified to the linker and prefixed with the
1256 " These will be passed unmodified to the linker and prefixed with\n" 1273 "lib_prefix" attribute of the linker tool. Generally you would set the
1257 " the \"lib_prefix\" attribute of the linker tool. Generally you\n" 1274 "lib_dirs" so the given library is found. Your BUILD.gn file should not
1258 " would set the \"lib_dirs\" so the given library is found. Your\n" 1275 specify the switch (like "-l"): this will be encoded in the "lib_prefix"
1259 " BUILD.gn file should not specify the switch (like \"-l\"): this\n" 1276 of the tool.
1260 " will be encoded in the \"lib_prefix\" of the tool.\n" 1277
1261 "\n" 1278 Apple frameworks
1262 " Apple frameworks\n" 1279 System libraries ending in ".framework" will be special-cased: the switch
1263 " System libraries ending in \".framework\" will be special-cased:\n" 1280 "-framework" will be prepended instead of the lib_prefix, and the
1264 " the switch \"-framework\" will be prepended instead of the\n" 1281 ".framework" suffix will be trimmed. This is to support the way Mac links
1265 " lib_prefix, and the \".framework\" suffix will be trimmed. This is\n" 1282 framework dependencies.
1266 " to support the way Mac links framework dependencies.\n" 1283 )"
1267 COMMON_ORDERING_HELP 1284 COMMON_ORDERING_HELP
1268 LIBS_AND_LIB_DIRS_ORDERING_HELP 1285 LIBS_AND_LIB_DIRS_ORDERING_HELP
1269 "\n" 1286 R"(
1270 "Examples\n" 1287 Examples
1271 "\n" 1288
1272 " On Windows:\n" 1289 On Windows:
1273 " libs = [ \"ctl3d.lib\" ]\n" 1290 libs = [ "ctl3d.lib" ]
1274 "\n" 1291
1275 " On Linux:\n" 1292 On Linux:
1276 " libs = [ \"ld\" ]\n"; 1293 libs = [ "ld" ]
1294 )";
1277 1295
1278 const char kOutputExtension[] = "output_extension"; 1296 const char kOutputExtension[] = "output_extension";
1279 const char kOutputExtension_HelpShort[] = 1297 const char kOutputExtension_HelpShort[] =
1280 "output_extension: [string] Value to use for the output's file extension."; 1298 "output_extension: [string] Value to use for the output's file extension.";
1281 const char kOutputExtension_Help[] = 1299 const char kOutputExtension_Help[] =
1282 "output_extension: Value to use for the output's file extension.\n" 1300 R"(output_extension: Value to use for the output's file extension.
1283 "\n" 1301
1284 " Normally the file extension for a target is based on the target\n" 1302 Normally the file extension for a target is based on the target type and the
1285 " type and the operating system, but in rare cases you will need to\n" 1303 operating system, but in rare cases you will need to override the name (for
1286 " override the name (for example to use \"libfreetype.so.6\" instead\n" 1304 example to use "libfreetype.so.6" instead of libfreetype.so on Linux).
1287 " of libfreetype.so on Linux).\n" 1305
1288 "\n" 1306 This value should not include a leading dot. If undefined, the default
1289 " This value should not include a leading dot. If undefined, the default\n" 1307 specified on the tool will be used. If set to the empty string, no output
1290 " specified on the tool will be used. If set to the empty string, no\n" 1308 extension will be used.
1291 " output extension will be used.\n" 1309
1292 "\n" 1310 The output_extension will be used to set the "{{output_extension}}" expansion
1293 " The output_extension will be used to set the \"{{output_extension}}\"\n" 1311 which the linker tool will generally use to specify the output file name. See
1294 " expansion which the linker tool will generally use to specify the\n" 1312 "gn help tool".
1295 " output file name. See \"gn help tool\".\n" 1313
1296 "\n" 1314 Example
1297 "Example\n" 1315
1298 "\n" 1316 shared_library("freetype") {
1299 " shared_library(\"freetype\") {\n" 1317 if (is_linux) {
1300 " if (is_linux) {\n" 1318 # Call the output "libfreetype.so.6"
1301 " # Call the output \"libfreetype.so.6\"\n" 1319 output_extension = "so.6"
1302 " output_extension = \"so.6\"\n" 1320 }
1303 " }\n" 1321 ...
1304 " ...\n" 1322 }
1305 " }\n" 1323
1306 "\n" 1324 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel
1307 " # On Windows, generate a \"mysettings.cpl\" control panel applet.\n" 1325 # applets are actually special shared libraries.
1308 " # Control panel applets are actually special shared libraries.\n" 1326 if (is_win) {
1309 " if (is_win) {\n" 1327 shared_library("mysettings") {
1310 " shared_library(\"mysettings\") {\n" 1328 output_extension = "cpl"
1311 " output_extension = \"cpl\"\n" 1329 ...
1312 " ...\n" 1330 }
1313 " }\n" 1331 }
1314 " }\n"; 1332 )";
1315 1333
1316 const char kOutputDir[] = "output_dir"; 1334 const char kOutputDir[] = "output_dir";
1317 const char kOutputDir_HelpShort[] = 1335 const char kOutputDir_HelpShort[] =
1318 "output_dir: [directory] Directory to put output file in."; 1336 "output_dir: [directory] Directory to put output file in.";
1319 const char kOutputDir_Help[] = 1337 const char kOutputDir_Help[] =
1320 "output_dir: [directory] Directory to put output file in.\n" 1338 R"(output_dir: [directory] Directory to put output file in.
1321 "\n" 1339
1322 " For library and executable targets, overrides the directory for the\n" 1340 For library and executable targets, overrides the directory for the final
1323 " final output. This must be in the root_build_dir or a child thereof.\n" 1341 output. This must be in the root_build_dir or a child thereof.
1324 "\n" 1342
1325 " This should generally be in the root_out_dir or a subdirectory thereof\n" 1343 This should generally be in the root_out_dir or a subdirectory thereof (the
1326 " (the root_out_dir will be the same as the root_build_dir for the\n" 1344 root_out_dir will be the same as the root_build_dir for the default
1327 " default toolchain, and will be a subdirectory for other toolchains).\n" 1345 toolchain, and will be a subdirectory for other toolchains). Not putting the
1328 " Not putting the output in a subdirectory of root_out_dir can result\n" 1346 output in a subdirectory of root_out_dir can result in collisions between
1329 " in collisions between different toolchains, so you will need to take\n" 1347 different toolchains, so you will need to take steps to ensure that your
1330 " steps to ensure that your target is only present in one toolchain.\n" 1348 target is only present in one toolchain.
1331 "\n" 1349
1332 " Normally the toolchain specifies the output directory for libraries\n" 1350 Normally the toolchain specifies the output directory for libraries and
1333 " and executables (see \"gn help tool\"). You will have to consult that\n" 1351 executables (see "gn help tool"). You will have to consult that for the
1334 " for the default location. The default location will be used if\n" 1352 default location. The default location will be used if output_dir is
1335 " output_dir is undefined or empty.\n" 1353 undefined or empty.
1336 "\n" 1354
1337 "Example\n" 1355 Example
1338 "\n" 1356
1339 " shared_library(\"doom_melon\") {\n" 1357 shared_library("doom_melon") {
1340 " output_dir = \"$root_out_dir/plugin_libs\"\n" 1358 output_dir = "$root_out_dir/plugin_libs"
1341 " ...\n" 1359 ...
1342 " }\n"; 1360 }
1361 )";
1343 1362
1344 const char kOutputName[] = "output_name"; 1363 const char kOutputName[] = "output_name";
1345 const char kOutputName_HelpShort[] = 1364 const char kOutputName_HelpShort[] =
1346 "output_name: [string] Name for the output file other than the default."; 1365 "output_name: [string] Name for the output file other than the default.";
1347 const char kOutputName_Help[] = 1366 const char kOutputName_Help[] =
1348 "output_name: Define a name for the output file other than the default.\n" 1367 R"(output_name: Define a name for the output file other than the default.
1349 "\n" 1368
1350 " Normally the output name of a target will be based on the target name,\n" 1369 Normally the output name of a target will be based on the target name, so the
1351 " so the target \"//foo/bar:bar_unittests\" will generate an output\n" 1370 target "//foo/bar:bar_unittests" will generate an output file such as
1352 " file such as \"bar_unittests.exe\" (using Windows as an example).\n" 1371 "bar_unittests.exe" (using Windows as an example).
1353 "\n" 1372
1354 " Sometimes you will want an alternate name to avoid collisions or\n" 1373 Sometimes you will want an alternate name to avoid collisions or if the
1355 " if the internal name isn't appropriate for public distribution.\n" 1374 internal name isn't appropriate for public distribution.
1356 "\n" 1375
1357 " The output name should have no extension or prefixes, these will be\n" 1376 The output name should have no extension or prefixes, these will be added
1358 " added using the default system rules. For example, on Linux an output\n" 1377 using the default system rules. For example, on Linux an output name of "foo"
1359 " name of \"foo\" will produce a shared library \"libfoo.so\". There\n" 1378 will produce a shared library "libfoo.so". There is no way to override the
1360 " is no way to override the output prefix of a linker tool on a per-\n" 1379 output prefix of a linker tool on a per- target basis. If you need more
1361 " target basis. If you need more flexibility, create a copy target\n" 1380 flexibility, create a copy target to produce the file you want.
1362 " to produce the file you want.\n" 1381
1363 "\n" 1382 This variable is valid for all binary output target types.
1364 " This variable is valid for all binary output target types.\n" 1383
1365 "\n" 1384 Example
1366 "Example\n" 1385
1367 "\n" 1386 static_library("doom_melon") {
1368 " static_library(\"doom_melon\") {\n" 1387 output_name = "fluffy_bunny"
1369 " output_name = \"fluffy_bunny\"\n" 1388 }
1370 " }\n"; 1389 )";
1371 1390
1372 const char kOutputPrefixOverride[] = "output_prefix_override"; 1391 const char kOutputPrefixOverride[] = "output_prefix_override";
1373 const char kOutputPrefixOverride_HelpShort[] = 1392 const char kOutputPrefixOverride_HelpShort[] =
1374 "output_prefix_override: [boolean] Don't use prefix for output name."; 1393 "output_prefix_override: [boolean] Don't use prefix for output name.";
1375 const char kOutputPrefixOverride_Help[] = 1394 const char kOutputPrefixOverride_Help[] =
1376 "output_prefix_override: Don't use prefix for output name.\n" 1395 R"(output_prefix_override: Don't use prefix for output name.
1377 "\n" 1396
1378 " A boolean that overrides the output prefix for a target. Defaults to\n" 1397 A boolean that overrides the output prefix for a target. Defaults to false.
1379 " false.\n" 1398
1380 "\n" 1399 Some systems use prefixes for the names of the final target output file. The
1381 " Some systems use prefixes for the names of the final target output\n" 1400 normal example is "libfoo.so" on Linux for a target named "foo".
1382 " file. The normal example is \"libfoo.so\" on Linux for a target\n" 1401
1383 " named \"foo\".\n" 1402 The output prefix for a given target type is specified on the linker tool
1384 "\n" 1403 (see "gn help tool"). Sometimes this prefix is undesired.
1385 " The output prefix for a given target type is specified on the linker\n" 1404
1386 " tool (see \"gn help tool\"). Sometimes this prefix is undesired.\n" 1405 See also "gn help output_extension".
1387 "\n" 1406
1388 " See also \"gn help output_extension\".\n" 1407 Example
1389 "\n" 1408
1390 "Example\n" 1409 shared_library("doom_melon") {
1391 "\n" 1410 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag
1392 " shared_library(\"doom_melon\") {\n" 1411 # will produce "doom_melon.so".
1393 " # Normally this will produce \"libdoom_melon.so\" on Linux, setting\n" 1412 output_prefix_override = true
1394 " # Setting this flag will produce \"doom_melon.so\".\n" 1413 ...
1395 " output_prefix_override = true\n" 1414 }
1396 " ...\n" 1415 )";
1397 " }\n";
1398 1416
1399 const char kOutputs[] = "outputs"; 1417 const char kOutputs[] = "outputs";
1400 const char kOutputs_HelpShort[] = 1418 const char kOutputs_HelpShort[] =
1401 "outputs: [file list] Output files for actions and copy targets."; 1419 "outputs: [file list] Output files for actions and copy targets.";
1402 const char kOutputs_Help[] = 1420 const char kOutputs_Help[] =
1403 "outputs: Output files for actions and copy targets.\n" 1421 R"(outputs: Output files for actions and copy targets.
1404 "\n" 1422
1405 " Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n" 1423 Outputs is valid for "copy", "action", and "action_foreach" target types and
1406 " target types and indicates the resulting files. Outputs must always\n" 1424 indicates the resulting files. Outputs must always refer to files in the
1407 " refer to files in the build directory.\n" 1425 build directory.
1408 "\n" 1426
1409 " copy\n" 1427 copy
1410 " Copy targets should have exactly one entry in the outputs list. If\n" 1428 Copy targets should have exactly one entry in the outputs list. If there is
1411 " there is exactly one source, this can be a literal file name or a\n" 1429 exactly one source, this can be a literal file name or a source expansion.
1412 " source expansion. If there is more than one source, this must\n" 1430 If there is more than one source, this must contain a source expansion to
1413 " contain a source expansion to map a single input name to a single\n" 1431 map a single input name to a single output name. See "gn help copy".
1414 " output name. See \"gn help copy\".\n" 1432
1415 "\n" 1433 action_foreach
1416 " action_foreach\n" 1434 Action_foreach targets must always use source expansions to map input files
1417 " Action_foreach targets must always use source expansions to map\n" 1435 to output files. There can be more than one output, which means that each
1418 " input files to output files. There can be more than one output,\n" 1436 invocation of the script will produce a set of files (presumably based on
1419 " which means that each invocation of the script will produce a set of\n" 1437 the name of the input file). See "gn help action_foreach".
1420 " files (presumably based on the name of the input file). See\n" 1438
1421 " \"gn help action_foreach\".\n" 1439 action
1422 "\n" 1440 Action targets (excluding action_foreach) must list literal output file(s)
1423 " action\n" 1441 with no source expansions. See "gn help action".
1424 " Action targets (excluding action_foreach) must list literal output\n" 1442 )";
1425 " file(s) with no source expansions. See \"gn help action\".\n";
1426 1443
1427 const char kPrecompiledHeader[] = "precompiled_header"; 1444 const char kPrecompiledHeader[] = "precompiled_header";
1428 const char kPrecompiledHeader_HelpShort[] = 1445 const char kPrecompiledHeader_HelpShort[] =
1429 "precompiled_header: [string] Header file to precompile."; 1446 "precompiled_header: [string] Header file to precompile.";
1430 const char kPrecompiledHeader_Help[] = 1447 const char kPrecompiledHeader_Help[] =
1431 "precompiled_header: [string] Header file to precompile.\n" 1448 R"(precompiled_header: [string] Header file to precompile.
1432 "\n" 1449
1433 " Precompiled headers will be used when a target specifies this\n" 1450 Precompiled headers will be used when a target specifies this value, or a
1434 " value, or a config applying to this target specifies this value.\n" 1451 config applying to this target specifies this value. In addition, the tool
1435 " In addition, the tool corresponding to the source files must also\n" 1452 corresponding to the source files must also specify precompiled headers (see
1436 " specify precompiled headers (see \"gn help tool\"). The tool\n" 1453 "gn help tool"). The tool will also specify what type of precompiled headers
1437 " will also specify what type of precompiled headers to use.\n" 1454 to use.
1438 "\n" 1455
1439 " The precompiled header/source variables can be specified on a target\n" 1456 The precompiled header/source variables can be specified on a target or a
1440 " or a config, but must be the same for all configs applying to a given\n" 1457 config, but must be the same for all configs applying to a given target since
1441 " target since a target can only have one precompiled header.\n" 1458 a target can only have one precompiled header.
1442 "\n" 1459
1443 "MSVC precompiled headers\n" 1460 MSVC precompiled headers
1444 "\n" 1461
1445 " When using MSVC-style precompiled headers, the \"precompiled_header\"\n" 1462 When using MSVC-style precompiled headers, the "precompiled_header" value is
1446 " value is a string corresponding to the header. This is NOT a path\n" 1463 a string corresponding to the header. This is NOT a path to a file that GN
1447 " to a file that GN recognises, but rather the exact string that appears\n" 1464 recognises, but rather the exact string that appears in quotes after an
1448 " in quotes after an #include line in source code. The compiler will\n" 1465 #include line in source code. The compiler will match this string against
1449 " match this string against includes or forced includes (/FI).\n" 1466 includes or forced includes (/FI).
1450 "\n" 1467
1451 " MSVC also requires a source file to compile the header with. This must\n" 1468 MSVC also requires a source file to compile the header with. This must be
1452 " be specified by the \"precompiled_source\" value. In contrast to the\n" 1469 specified by the "precompiled_source" value. In contrast to the header value,
1453 " header value, this IS a GN-style file name, and tells GN which source\n" 1470 this IS a GN-style file name, and tells GN which source file to compile to
1454 " file to compile to make the .pch file used for subsequent compiles.\n" 1471 make the .pch file used for subsequent compiles.
1455 "\n" 1472
1456 " If you use both C and C++ sources, the precompiled header and source\n" 1473 If you use both C and C++ sources, the precompiled header and source file
1457 " file will be compiled using both tools. You will want to make sure\n" 1474 will be compiled using both tools. You will want to make sure to wrap C++
1458 " to wrap C++ includes in __cplusplus #ifdefs so the file will compile\n" 1475 includes in __cplusplus #ifdefs so the file will compile in C mode.
1459 " in C mode.\n" 1476
1460 "\n" 1477 For example, if the toolchain specifies MSVC headers:
1461 " For example, if the toolchain specifies MSVC headers:\n" 1478
1462 "\n" 1479 toolchain("vc_x64") {
1463 " toolchain(\"vc_x64\") {\n" 1480 ...
1464 " ...\n" 1481 tool("cxx") {
1465 " tool(\"cxx\") {\n" 1482 precompiled_header_type = "msvc"
1466 " precompiled_header_type = \"msvc\"\n" 1483 ...
1467 " ...\n" 1484
1468 "\n" 1485 You might make a config like this:
1469 " You might make a config like this:\n" 1486
1470 "\n" 1487 config("use_precompiled_headers") {
1471 " config(\"use_precompiled_headers\") {\n" 1488 precompiled_header = "build/precompile.h"
1472 " precompiled_header = \"build/precompile.h\"\n" 1489 precompiled_source = "//build/precompile.cc"
1473 " precompiled_source = \"//build/precompile.cc\"\n" 1490
1474 "\n" 1491 # Either your source files should #include "build/precompile.h"
1475 " # Either your source files should #include \"build/precompile.h\"\n" 1492 # first, or you can do this to force-include the header.
1476 " # first, or you can do this to force-include the header.\n" 1493 cflags = [ "/FI$precompiled_header" ]
1477 " cflags = [ \"/FI$precompiled_header\" ]\n" 1494 }
1478 " }\n" 1495
1479 "\n" 1496 And then define a target that uses the config:
1480 " And then define a target that uses the config:\n" 1497
1481 "\n" 1498 executable("doom_melon") {
1482 " executable(\"doom_melon\") {\n" 1499 configs += [ ":use_precompiled_headers" ]
1483 " configs += [ \":use_precompiled_headers\" ]\n" 1500 ...
1484 " ...\n" 1501 )";
1485 "\n";
1486 1502
1487 const char kPrecompiledSource[] = "precompiled_source"; 1503 const char kPrecompiledSource[] = "precompiled_source";
1488 const char kPrecompiledSource_HelpShort[] = 1504 const char kPrecompiledSource_HelpShort[] =
1489 "precompiled_source: [file name] Source file to precompile."; 1505 "precompiled_source: [file name] Source file to precompile.";
1490 const char kPrecompiledSource_Help[] = 1506 const char kPrecompiledSource_Help[] =
1491 "precompiled_source: [file name] Source file to precompile.\n" 1507 R"(precompiled_source: [file name] Source file to precompile.
1492 "\n" 1508
1493 " The source file that goes along with the precompiled_header when\n" 1509 The source file that goes along with the precompiled_header when using
1494 " using \"msvc\"-style precompiled headers. It will be implicitly added\n" 1510 "msvc"-style precompiled headers. It will be implicitly added to the sources
1495 " to the sources of the target. See \"gn help precompiled_header\".\n"; 1511 of the target. See "gn help precompiled_header".
1512 )";
1496 1513
1497 const char kProductType[] = "product_type"; 1514 const char kProductType[] = "product_type";
1498 const char kProductType_HelpShort[] = 1515 const char kProductType_HelpShort[] =
1499 "product_type: [string] Product type for Xcode projects."; 1516 "product_type: [string] Product type for Xcode projects.";
1500 const char kProductType_Help[] = 1517 const char kProductType_Help[] =
1501 "product_type: Product type for Xcode projects.\n" 1518 R"(product_type: Product type for Xcode projects.
1502 "\n" 1519
1503 " Correspond to the type of the product of a create_bundle target. Only\n" 1520 Correspond to the type of the product of a create_bundle target. Only
1504 " meaningful to Xcode (used as part of the Xcode project generation).\n" 1521 meaningful to Xcode (used as part of the Xcode project generation).
1505 "\n" 1522
1506 " When generating Xcode project files, only create_bundle target with\n" 1523 When generating Xcode project files, only create_bundle target with a
1507 " a non-empty product_type will have a corresponding target in Xcode\n" 1524 non-empty product_type will have a corresponding target in Xcode project.
1508 " project.\n"; 1525 )";
1509 1526
1510 const char kPublic[] = "public"; 1527 const char kPublic[] = "public";
1511 const char kPublic_HelpShort[] = 1528 const char kPublic_HelpShort[] =
1512 "public: [file list] Declare public header files for a target."; 1529 "public: [file list] Declare public header files for a target.";
1513 const char kPublic_Help[] = 1530 const char kPublic_Help[] =
1514 "public: Declare public header files for a target.\n" 1531 R"(public: Declare public header files for a target.
1515 "\n" 1532
1516 " A list of files that other targets can include. These permissions are\n" 1533 A list of files that other targets can include. These permissions are checked
1517 " checked via the \"check\" command (see \"gn help check\").\n" 1534 via the "check" command (see "gn help check").
1518 "\n" 1535
1519 " If no public files are declared, other targets (assuming they have\n" 1536 If no public files are declared, other targets (assuming they have visibility
1520 " visibility to depend on this target can include any file in the\n" 1537 to depend on this target can include any file in the sources list. If this
1521 " sources list. If this variable is defined on a target, dependent\n" 1538 variable is defined on a target, dependent targets may only include files on
1522 " targets may only include files on this whitelist.\n" 1539 this whitelist.
1523 "\n" 1540
1524 " Header file permissions are also subject to visibility. A target\n" 1541 Header file permissions are also subject to visibility. A target must be
1525 " must be visible to another target to include any files from it at all\n" 1542 visible to another target to include any files from it at all and the public
1526 " and the public headers indicate which subset of those files are\n" 1543 headers indicate which subset of those files are permitted. See "gn help
1527 " permitted. See \"gn help visibility\" for more.\n" 1544 visibility" for more.
1528 "\n" 1545
1529 " Public files are inherited through the dependency tree. So if there is\n" 1546 Public files are inherited through the dependency tree. So if there is a
1530 " a dependency A -> B -> C, then A can include C's public headers.\n" 1547 dependency A -> B -> C, then A can include C's public headers. However, the
1531 " However, the same is NOT true of visibility, so unless A is in C's\n" 1548 same is NOT true of visibility, so unless A is in C's visibility list, the
1532 " visibility list, the include will be rejected.\n" 1549 include will be rejected.
1533 "\n" 1550
1534 " GN only knows about files declared in the \"sources\" and \"public\"\n" 1551 GN only knows about files declared in the "sources" and "public" sections of
1535 " sections of targets. If a file is included that is not known to the\n" 1552 targets. If a file is included that is not known to the build, it will be
1536 " build, it will be allowed.\n" 1553 allowed.
1537 "\n" 1554
1538 "Examples\n" 1555 Examples
1539 "\n" 1556
1540 " These exact files are public:\n" 1557 These exact files are public:
1541 " public = [ \"foo.h\", \"bar.h\" ]\n" 1558 public = [ "foo.h", "bar.h" ]
1542 "\n" 1559
1543 " No files are public (no targets may include headers from this one):\n" 1560 No files are public (no targets may include headers from this one):
1544 " public = []\n"; 1561 public = []
1562 )";
1545 1563
1546 const char kPublicConfigs[] = "public_configs"; 1564 const char kPublicConfigs[] = "public_configs";
1547 const char kPublicConfigs_HelpShort[] = 1565 const char kPublicConfigs_HelpShort[] =
1548 "public_configs: [label list] Configs applied to dependents."; 1566 "public_configs: [label list] Configs applied to dependents.";
1549 const char kPublicConfigs_Help[] = 1567 const char kPublicConfigs_Help[] =
1550 "public_configs: Configs to be applied on dependents.\n" 1568 R"(public_configs: Configs to be applied on dependents.
1551 "\n" 1569
1552 " A list of config labels.\n" 1570 A list of config labels.
1553 "\n" 1571
1554 " Targets directly depending on this one will have the configs listed in\n" 1572 Targets directly depending on this one will have the configs listed in this
1555 " this variable added to them. These configs will also apply to the\n" 1573 variable added to them. These configs will also apply to the current target.
1556 " current target.\n" 1574
1557 "\n" 1575 This addition happens in a second phase once a target and all of its
1558 " This addition happens in a second phase once a target and all of its\n" 1576 dependencies have been resolved. Therefore, a target will not see these
1559 " dependencies have been resolved. Therefore, a target will not see\n" 1577 force-added configs in their "configs" variable while the script is running,
1560 " these force-added configs in their \"configs\" variable while the\n" 1578 and then can not be removed. As a result, this capability should generally
1561 " script is running, and then can not be removed. As a result, this\n" 1579 only be used to add defines and include directories necessary to compile a
1562 " capability should generally only be used to add defines and include\n" 1580 target's headers.
1563 " directories necessary to compile a target's headers.\n" 1581
1564 "\n" 1582 See also "all_dependent_configs".
1565 " See also \"all_dependent_configs\".\n" 1583 )"
1566 COMMON_ORDERING_HELP; 1584 COMMON_ORDERING_HELP;
1567 1585
1568 const char kPublicDeps[] = "public_deps"; 1586 const char kPublicDeps[] = "public_deps";
1569 const char kPublicDeps_HelpShort[] = 1587 const char kPublicDeps_HelpShort[] =
1570 "public_deps: [label list] Declare public dependencies."; 1588 "public_deps: [label list] Declare public dependencies.";
1571 const char kPublicDeps_Help[] = 1589 const char kPublicDeps_Help[] =
1572 "public_deps: Declare public dependencies.\n" 1590 R"(public_deps: Declare public dependencies.
1573 "\n" 1591
1574 " Public dependencies are like private dependencies (see\n" 1592 Public dependencies are like private dependencies (see "gn help deps") but
1575 " \"gn help deps\") but additionally express that the current target\n" 1593 additionally express that the current target exposes the listed deps as part
1576 " exposes the listed deps as part of its public API.\n" 1594 of its public API.
1577 "\n" 1595
1578 " This has several ramifications:\n" 1596 This has several ramifications:
1579 "\n" 1597
1580 " - public_configs that are part of the dependency are forwarded\n" 1598 - public_configs that are part of the dependency are forwarded to direct
1581 " to direct dependents.\n" 1599 dependents.
1582 "\n" 1600
1583 " - Public headers in the dependency are usable by dependents\n" 1601 - Public headers in the dependency are usable by dependents (includes do
1584 " (includes do not require a direct dependency or visibility).\n" 1602 not require a direct dependency or visibility).
1585 "\n" 1603
1586 " - If the current target is a shared library, other shared libraries\n" 1604 - If the current target is a shared library, other shared libraries that it
1587 " that it publicly depends on (directly or indirectly) are\n" 1605 publicly depends on (directly or indirectly) are propagated up the
1588 " propagated up the dependency tree to dependents for linking.\n" 1606 dependency tree to dependents for linking.
1589 "\n" 1607
1590 "Discussion\n" 1608 Discussion
1591 "\n" 1609
1592 " Say you have three targets: A -> B -> C. C's visibility may allow\n" 1610 Say you have three targets: A -> B -> C. C's visibility may allow B to depend
1593 " B to depend on it but not A. Normally, this would prevent A from\n" 1611 on it but not A. Normally, this would prevent A from including any headers
1594 " including any headers from C, and C's public_configs would apply\n" 1612 from C, and C's public_configs would apply only to B.
1595 " only to B.\n" 1613
1596 "\n" 1614 If B lists C in its public_deps instead of regular deps, A will now inherit
1597 " If B lists C in its public_deps instead of regular deps, A will now\n" 1615 C's public_configs and the ability to include C's public headers.
1598 " inherit C's public_configs and the ability to include C's public\n" 1616
1599 " headers.\n" 1617 Generally if you are writing a target B and you include C's headers as part
1600 "\n" 1618 of B's public headers, or targets depending on B should consider B and C to
1601 " Generally if you are writing a target B and you include C's headers\n" 1619 be part of a unit, you should use public_deps instead of deps.
1602 " as part of B's public headers, or targets depending on B should\n" 1620
1603 " consider B and C to be part of a unit, you should use public_deps\n" 1621 Example
1604 " instead of deps.\n" 1622
1605 "\n" 1623 # This target can include files from "c" but not from
1606 "Example\n" 1624 # "super_secret_implementation_details".
1607 "\n" 1625 executable("a") {
1608 " # This target can include files from \"c\" but not from\n" 1626 deps = [ ":b" ]
1609 " # \"super_secret_implementation_details\".\n" 1627 }
1610 " executable(\"a\") {\n" 1628
1611 " deps = [ \":b\" ]\n" 1629 shared_library("b") {
1612 " }\n" 1630 deps = [ ":super_secret_implementation_details" ]
1613 "\n" 1631 public_deps = [ ":c" ]
1614 " shared_library(\"b\") {\n" 1632 }
1615 " deps = [ \":super_secret_implementation_details\" ]\n" 1633 )";
1616 " public_deps = [ \":c\" ]\n"
1617 " }\n";
1618 1634
1619 const char kResponseFileContents[] = "response_file_contents"; 1635 const char kResponseFileContents[] = "response_file_contents";
1620 const char kResponseFileContents_HelpShort[] = 1636 const char kResponseFileContents_HelpShort[] =
1621 "response_file_contents: [string list] Contents of .rsp file for actions."; 1637 "response_file_contents: [string list] Contents of .rsp file for actions.";
1622 const char kResponseFileContents_Help[] = 1638 const char kResponseFileContents_Help[] =
1623 "response_file_contents: Contents of a response file for actions.\n" 1639 R"*(response_file_contents: Contents of a response file for actions.
1624 "\n" 1640
1625 " Sometimes the arguments passed to a script can be too long for the\n" 1641 Sometimes the arguments passed to a script can be too long for the system's
1626 " system's command-line capabilities. This is especially the case on\n" 1642 command-line capabilities. This is especially the case on Windows where the
1627 " Windows where the maximum command-line length is less than 8K. A\n" 1643 maximum command-line length is less than 8K. A response file allows you to
1628 " response file allows you to pass an unlimited amount of data to a\n" 1644 pass an unlimited amount of data to a script in a temporary file for an
1629 " script in a temporary file for an action or action_foreach target.\n" 1645 action or action_foreach target.
1630 "\n" 1646
1631 " If the response_file_contents variable is defined and non-empty, the\n" 1647 If the response_file_contents variable is defined and non-empty, the list
1632 " list will be treated as script args (including possibly substitution\n" 1648 will be treated as script args (including possibly substitution patterns)
1633 " patterns) that will be written to a temporary file at build time.\n" 1649 that will be written to a temporary file at build time. The name of the
1634 " The name of the temporary file will be substituted for\n" 1650 temporary file will be substituted for "{{response_file_name}}" in the script
1635 " \"{{response_file_name}}\" in the script args.\n" 1651 args.
1636 "\n" 1652
1637 " The response file contents will always be quoted and escaped\n" 1653 The response file contents will always be quoted and escaped according to
1638 " according to Unix shell rules. To parse the response file, the Python\n" 1654 Unix shell rules. To parse the response file, the Python script should use
1639 " script should use \"shlex.split(file_contents)\".\n" 1655 "shlex.split(file_contents)".
1640 "\n" 1656
1641 "Example\n" 1657 Example
1642 "\n" 1658
1643 " action(\"process_lots_of_files\") {\n" 1659 action("process_lots_of_files") {
1644 " script = \"process.py\",\n" 1660 script = "process.py",
1645 " inputs = [ ... huge list of files ... ]\n" 1661 inputs = [ ... huge list of files ... ]
1646 "\n" 1662
1647 " # Write all the inputs to a response file for the script. Also,\n" 1663 # Write all the inputs to a response file for the script. Also,
1648 " # make the paths relative to the script working directory.\n" 1664 # make the paths relative to the script working directory.
1649 " response_file_contents = rebase_path(inputs, root_build_dir)\n" 1665 response_file_contents = rebase_path(inputs, root_build_dir)
1650 "\n" 1666
1651 " # The script expects the name of the response file in --file-list.\n" 1667 # The script expects the name of the response file in --file-list.
1652 " args = [\n" 1668 args = [
1653 " \"--enable-foo\",\n" 1669 "--enable-foo",
1654 " \"--file-list={{response_file_name}}\",\n" 1670 "--file-list={{response_file_name}}",
1655 " ]\n" 1671 ]
1656 " }\n"; 1672 }
1673 )*";
1657 1674
1658 const char kScript[] = "script"; 1675 const char kScript[] = "script";
1659 const char kScript_HelpShort[] = 1676 const char kScript_HelpShort[] =
1660 "script: [file name] Script file for actions."; 1677 "script: [file name] Script file for actions.";
1661 const char kScript_Help[] = 1678 const char kScript_Help[] =
1662 "script: Script file for actions.\n" 1679 R"(script: Script file for actions.
1663 "\n" 1680
1664 " An absolute or buildfile-relative file name of a Python script to run\n" 1681 An absolute or buildfile-relative file name of a Python script to run for a
1665 " for a action and action_foreach targets (see \"gn help action\" and\n" 1682 action and action_foreach targets (see "gn help action" and "gn help
1666 " \"gn help action_foreach\").\n"; 1683 action_foreach").
1684 )";
1667 1685
1668 const char kSources[] = "sources"; 1686 const char kSources[] = "sources";
1669 const char kSources_HelpShort[] = 1687 const char kSources_HelpShort[] =
1670 "sources: [file list] Source files for a target."; 1688 "sources: [file list] Source files for a target.";
1671 const char kSources_Help[] = 1689 const char kSources_Help[] =
1672 "sources: Source files for a target\n" 1690 R"(sources: Source files for a target
1673 "\n" 1691
1674 " A list of files. Non-absolute paths will be resolved relative to the\n" 1692 A list of files. Non-absolute paths will be resolved relative to the current
1675 " current build file.\n" 1693 build file.
1676 "\n" 1694
1677 "Sources for binary targets\n" 1695 Sources for binary targets
1678 "\n" 1696
1679 " For binary targets (source sets, executables, and libraries), the\n" 1697 For binary targets (source sets, executables, and libraries), the known file
1680 " known file types will be compiled with the associated tools. Unknown\n" 1698 types will be compiled with the associated tools. Unknown file types and
1681 " file types and headers will be skipped. However, you should still\n" 1699 headers will be skipped. However, you should still list all C/C+ header files
1682 " list all C/C+ header files so GN knows about the existance of those\n" 1700 so GN knows about the existance of those files for the purposes of include
1683 " files for the purposes of include checking.\n" 1701 checking.
1684 "\n" 1702
1685 " As a special case, a file ending in \".def\" will be treated as a\n" 1703 As a special case, a file ending in ".def" will be treated as a Windows
1686 " Windows module definition file. It will be appended to the link\n" 1704 module definition file. It will be appended to the link line with a
1687 " line with a preceeding \"/DEF:\" string. There must be at most one\n" 1705 preceeding "/DEF:" string. There must be at most one .def file in a target
1688 " .def file in a target and they do not cross dependency boundaries\n" 1706 and they do not cross dependency boundaries (so specifying a .def file in a
1689 " (so specifying a .def file in a static library or source set will have\n" 1707 static library or source set will have no effect on the executable or shared
1690 " no effect on the executable or shared library they're linked into).\n" 1708 library they're linked into).
1691 "\n" 1709
1692 "Sources for non-binary targets\n" 1710 Sources for non-binary targets
1693 "\n" 1711
1694 " action_foreach\n" 1712 action_foreach
1695 " The sources are the set of files that the script will be executed\n" 1713 The sources are the set of files that the script will be executed over. The
1696 " over. The script will run once per file.\n" 1714 script will run once per file.
1697 "\n" 1715
1698 " action\n" 1716 action
1699 " The sources will be treated the same as inputs. See " 1717 The sources will be treated the same as inputs. See "gn help inputs" for
1700 "\"gn help inputs\"\n" 1718 more information and usage advice.
1701 " for more information and usage advice.\n" 1719
1702 "\n" 1720 copy
1703 " copy\n" 1721 The source are the source files to copy.
1704 " The source are the source files to copy.\n"; 1722 )";
1705 1723
1706 const char kTestonly[] = "testonly"; 1724 const char kTestonly[] = "testonly";
1707 const char kTestonly_HelpShort[] = 1725 const char kTestonly_HelpShort[] =
1708 "testonly: [boolean] Declares a target must only be used for testing."; 1726 "testonly: [boolean] Declares a target must only be used for testing.";
1709 const char kTestonly_Help[] = 1727 const char kTestonly_Help[] =
1710 "testonly: Declares a target must only be used for testing.\n" 1728 R"(testonly: Declares a target must only be used for testing.
1711 "\n" 1729
1712 " Boolean. Defaults to false.\n" 1730 Boolean. Defaults to false.
1713 "\n" 1731
1714 " When a target is marked \"testonly = true\", it must only be depended\n" 1732 When a target is marked "testonly = true", it must only be depended on by
1715 " on by other test-only targets. Otherwise, GN will issue an error\n" 1733 other test-only targets. Otherwise, GN will issue an error that the
1716 " that the depenedency is not allowed.\n" 1734 depenedency is not allowed.
1717 "\n" 1735
1718 " This feature is intended to prevent accidentally shipping test code\n" 1736 This feature is intended to prevent accidentally shipping test code in a
1719 " in a final product.\n" 1737 final product.
1720 "\n" 1738
1721 "Example\n" 1739 Example
1722 "\n" 1740
1723 " source_set(\"test_support\") {\n" 1741 source_set("test_support") {
1724 " testonly = true\n" 1742 testonly = true
1725 " ...\n" 1743 ...
1726 " }\n"; 1744 }
1745 )";
1727 1746
1728 const char kVisibility[] = "visibility"; 1747 const char kVisibility[] = "visibility";
1729 const char kVisibility_HelpShort[] = 1748 const char kVisibility_HelpShort[] =
1730 "visibility: [label list] A list of labels that can depend on a target."; 1749 "visibility: [label list] A list of labels that can depend on a target.";
1731 const char kVisibility_Help[] = 1750 const char kVisibility_Help[] =
1732 "visibility: A list of labels that can depend on a target.\n" 1751 R"(visibility: A list of labels that can depend on a target.
1733 "\n" 1752
1734 " A list of labels and label patterns that define which targets can\n" 1753 A list of labels and label patterns that define which targets can depend on
1735 " depend on the current one. These permissions are checked via the\n" 1754 the current one. These permissions are checked via the "check" command (see
1736 " \"check\" command (see \"gn help check\").\n" 1755 "gn help check").
1737 "\n" 1756
1738 " If visibility is not defined, it defaults to public (\"*\").\n" 1757 If visibility is not defined, it defaults to public ("*").
1739 "\n" 1758
1740 " If visibility is defined, only the targets with labels that match it\n" 1759 If visibility is defined, only the targets with labels that match it can
1741 " can depend on the current target. The empty list means no targets\n" 1760 depend on the current target. The empty list means no targets can depend on
1742 " can depend on the current target.\n" 1761 the current target.
1743 "\n" 1762
1744 " Tip: Often you will want the same visibility for all targets in a\n" 1763 Tip: Often you will want the same visibility for all targets in a BUILD file.
1745 " BUILD file. In this case you can just put the definition at the top,\n" 1764 In this case you can just put the definition at the top, outside of any
1746 " outside of any target, and the targets will inherit that scope and see\n" 1765 target, and the targets will inherit that scope and see the definition.
1747 " the definition.\n" 1766
1748 "\n" 1767 Patterns
1749 "Patterns\n" 1768
1750 "\n" 1769 See "gn help label_pattern" for more details on what types of patterns are
1751 " See \"gn help label_pattern\" for more details on what types of\n" 1770 supported. If a toolchain is specified, only targets in that toolchain will
1752 " patterns are supported. If a toolchain is specified, only targets\n" 1771 be matched. If a toolchain is not specified on a pattern, targets in all
1753 " in that toolchain will be matched. If a toolchain is not specified on\n" 1772 toolchains will be matched.
1754 " a pattern, targets in all toolchains will be matched.\n" 1773
1755 "\n" 1774 Examples
1756 "Examples\n" 1775
1757 "\n" 1776 Only targets in the current buildfile ("private"):
1758 " Only targets in the current buildfile (\"private\"):\n" 1777 visibility = [ ":*" ]
1759 " visibility = [ \":*\" ]\n" 1778
1760 "\n" 1779 No targets (used for targets that should be leaf nodes):
1761 " No targets (used for targets that should be leaf nodes):\n" 1780 visibility = []
1762 " visibility = []\n" 1781
1763 "\n" 1782 Any target ("public", the default):
1764 " Any target (\"public\", the default):\n" 1783 visibility = [ "*" ]
1765 " visibility = [ \"*\" ]\n" 1784
1766 "\n" 1785 All targets in the current directory and any subdirectory:
1767 " All targets in the current directory and any subdirectory:\n" 1786 visibility = [ "./*" ]
1768 " visibility = [ \"./*\" ]\n" 1787
1769 "\n" 1788 Any target in "//bar/BUILD.gn":
1770 " Any target in \"//bar/BUILD.gn\":\n" 1789 visibility = [ "//bar:*" ]
1771 " visibility = [ \"//bar:*\" ]\n" 1790
1772 "\n" 1791 Any target in "//bar/" or any subdirectory thereof:
1773 " Any target in \"//bar/\" or any subdirectory thereof:\n" 1792 visibility = [ "//bar/*" ]
1774 " visibility = [ \"//bar/*\" ]\n" 1793
1775 "\n" 1794 Just these specific targets:
1776 " Just these specific targets:\n" 1795 visibility = [ ":mything", "//foo:something_else" ]
1777 " visibility = [ \":mything\", \"//foo:something_else\" ]\n" 1796
1778 "\n" 1797 Any target in the current directory and any subdirectory thereof, plus
1779 " Any target in the current directory and any subdirectory thereof, plus\n" 1798 any targets in "//bar/" and any subdirectory thereof.
1780 " any targets in \"//bar/\" and any subdirectory thereof.\n" 1799 visibility = [ "./*", "//bar/*" ]
1781 " visibility = [ \"./*\", \"//bar/*\" ]\n"; 1800 )";
1782 1801
1783 const char kWriteRuntimeDeps[] = "write_runtime_deps"; 1802 const char kWriteRuntimeDeps[] = "write_runtime_deps";
1784 const char kWriteRuntimeDeps_HelpShort[] = 1803 const char kWriteRuntimeDeps_HelpShort[] =
1785 "write_runtime_deps: Writes the target's runtime_deps to the given path."; 1804 "write_runtime_deps: Writes the target's runtime_deps to the given path.";
1786 const char kWriteRuntimeDeps_Help[] = 1805 const char kWriteRuntimeDeps_Help[] =
1787 "write_runtime_deps: Writes the target's runtime_deps to the given path.\n" 1806 R"(write_runtime_deps: Writes the target's runtime_deps to the given path.
1788 "\n" 1807
1789 " Does not synchronously write the file, but rather schedules it\n" 1808 Does not synchronously write the file, but rather schedules it to be written
1790 " to be written at the end of generation.\n" 1809 at the end of generation.
1791 "\n" 1810
1792 " If the file exists and the contents are identical to that being\n" 1811 If the file exists and the contents are identical to that being written, the
1793 " written, the file will not be updated. This will prevent unnecessary\n" 1812 file will not be updated. This will prevent unnecessary rebuilds of targets
1794 " rebuilds of targets that depend on this file.\n" 1813 that depend on this file.
1795 "\n" 1814
1796 " Path must be within the output directory.\n" 1815 Path must be within the output directory.
1797 "\n" 1816
1798 " See \"gn help runtime_deps\" for how the runtime dependencies are\n" 1817 See "gn help runtime_deps" for how the runtime dependencies are computed.
1799 " computed.\n" 1818
1800 "\n" 1819 The format of this file will list one file per line with no escaping. The
1801 " The format of this file will list one file per line with no escaping.\n" 1820 files will be relative to the root_build_dir. The first line of the file will
1802 " The files will be relative to the root_build_dir. The first line of\n" 1821 be the main output file of the target itself. The file contents will be the
1803 " the file will be the main output file of the target itself. The file\n" 1822 same as requesting the runtime deps be written on the command line (see "gn
1804 " contents will be the same as requesting the runtime deps be written on\n" 1823 help --runtime-deps-list-file").
1805 " the command line (see \"gn help --runtime-deps-list-file\").\n"; 1824 )";
1806 1825
1807 // ----------------------------------------------------------------------------- 1826 // -----------------------------------------------------------------------------
1808 1827
1809 VariableInfo::VariableInfo() 1828 VariableInfo::VariableInfo()
1810 : help_short(""), 1829 : help_short(""),
1811 help("") { 1830 help("") {
1812 } 1831 }
1813 1832
1814 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help) 1833 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help)
1815 : help_short(in_help_short), 1834 : help_short(in_help_short),
(...skipping 80 matching lines...) Expand 10 before | Expand all | Expand 10 after
1896 INSERT_VARIABLE(Testonly) 1915 INSERT_VARIABLE(Testonly)
1897 INSERT_VARIABLE(Visibility) 1916 INSERT_VARIABLE(Visibility)
1898 INSERT_VARIABLE(WriteRuntimeDeps) 1917 INSERT_VARIABLE(WriteRuntimeDeps)
1899 } 1918 }
1900 return info_map; 1919 return info_map;
1901 } 1920 }
1902 1921
1903 #undef INSERT_VARIABLE 1922 #undef INSERT_VARIABLE
1904 1923
1905 } // namespace variables 1924 } // namespace variables
OLDNEW
« no previous file with comments | « tools/gn/switches.cc ('k') | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698