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

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

Issue 2481423002: Convert gn docstrings to C++11 raw strings. (Closed)
Patch Set: Newlines 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
« tools/gn/function_template.cc ('K') | « 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 create_bun dle.
601 "Expansion of {{bundle_resources_dir}} in create_bundle.\n" 607
602 "\n" 608 A string corresponding to a path in $root_build_dir.
603 " A string corresponding to a path in $root_build_dir.\n" 609
604 "\n" 610 This string is used by the "create_bundle" target to expand the
605 " This string is used by the \"create_bundle\" target to expand the\n" 611 {{bundle_resources_dir}} of the "bundle_data" target it depends on. This must
606 " {{bundle_resources_dir}} of the \"bundle_data\" target it depends on.\n" 612 correspond to a path under "bundle_root_dir".
607 " This must correspond to a path under \"bundle_root_dir\".\n" 613
608 "\n" 614 See "gn help bundle_root_dir" for examples.
609 " See \"gn help bundle_root_dir\" for examples.\n"; 615 )";
610 616
611 const char kBundleDepsFilter[] = "bundle_deps_filter"; 617 const char kBundleDepsFilter[] = "bundle_deps_filter";
612 const char kBundleDepsFilter_HelpShort[] = 618 const char kBundleDepsFilter_HelpShort[] =
613 "bundle_deps_filter: [label list] A list of labels that are filtered out."; 619 "bundle_deps_filter: [label list] A list of labels that are filtered out.";
614 const char kBundleDepsFilter_Help[] = 620 const char kBundleDepsFilter_Help[] =
615 "bundle_deps_filter: [label list] A list of labels that are filtered out.\n" 621 R"(bundle_deps_filter: [label list] A list of labels that are filtered out.
616 "\n" 622
617 " A list of target labels.\n" 623 A list of target labels.
618 "\n" 624
619 " This list contains target label patterns that should be filtered out\n" 625 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" 626 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" 627 from the dependencies of the create_bundle target.
622 "\n" 628
623 " This is mostly useful when creating application extension bundle as\n" 629 This is mostly useful when creating application extension bundle as the
624 " the application extension has access to runtime resources from the\n" 630 application extension has access to runtime resources from the application
625 " application bundle and thus do not require a second copy.\n" 631 bundle and thus do not require a second copy.
626 "\n" 632
627 " See \"gn help create_bundle\" for more information.\n" 633 See "gn help create_bundle" for more information.
628 "\n" 634
629 "Example\n" 635 Example
630 "\n" 636
631 " create_bundle(\"today_extension\") {\n" 637 create_bundle("today_extension") {
632 " deps = [\n" 638 deps = [
633 " \"//base\"\n" 639 "//base"
634 " ]\n" 640 ]
635 " bundle_root_dir = \"$root_out_dir/today_extension.appex\"\n" 641 bundle_root_dir = "$root_out_dir/today_extension.appex"
636 " bundle_deps_filter = [\n" 642 bundle_deps_filter = [
637 " # The extension uses //base but does not use any function calling\n" 643 # 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" 644 # third_party/icu and thus does not need the icudtl.dat file.
639 " \"//third_party/icu:icudata\",\n" 645 "//third_party/icu:icudata",
640 " ]\n" 646 ]
641 " }\n"; 647 }
648 )";
642 649
643 const char kBundleExecutableDir[] = "bundle_executable_dir"; 650 const char kBundleExecutableDir[] = "bundle_executable_dir";
644 const char kBundleExecutableDir_HelpShort[] = 651 const char kBundleExecutableDir_HelpShort[] =
645 "bundle_executable_dir: " 652 "bundle_executable_dir: "
646 "Expansion of {{bundle_executable_dir}} in create_bundle"; 653 "Expansion of {{bundle_executable_dir}} in create_bundle";
647 const char kBundleExecutableDir_Help[] = 654 const char kBundleExecutableDir_Help[] =
648 "bundle_executable_dir: " 655 R"(bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_b undle.
649 "Expansion of {{bundle_executable_dir}} in create_bundle.\n" 656
650 "\n" 657 A string corresponding to a path in $root_build_dir.
651 " A string corresponding to a path in $root_build_dir.\n" 658
652 "\n" 659 This string is used by the "create_bundle" target to expand the
653 " This string is used by the \"create_bundle\" target to expand the\n" 660 {{bundle_executable_dir}} of the "bundle_data" target it depends on. This
654 " {{bundle_executable_dir}} of the \"bundle_data\" target it depends on.\n" 661 must correspond to a path under "bundle_root_dir".
655 " This must correspond to a path under \"bundle_root_dir\".\n" 662
656 "\n" 663 See "gn help bundle_root_dir" for examples.
657 " See \"gn help bundle_root_dir\" for examples.\n"; 664 )";
658 665
659 const char kBundlePlugInsDir[] = "bundle_plugins_dir"; 666 const char kBundlePlugInsDir[] = "bundle_plugins_dir";
660 const char kBundlePlugInsDir_HelpShort[] = 667 const char kBundlePlugInsDir_HelpShort[] =
661 "bundle_plugins_dir: " 668 "bundle_plugins_dir: "
662 "Expansion of {{bundle_plugins_dir}} in create_bundle."; 669 "Expansion of {{bundle_plugins_dir}} in create_bundle.";
663 const char kBundlePlugInsDir_Help[] = 670 const char kBundlePlugInsDir_Help[] =
664 "bundle_plugins_dir: " 671 R"(bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle.
665 "Expansion of {{bundle_plugins_dir}} in create_bundle.\n" 672
666 "\n" 673 A string corresponding to a path in $root_build_dir.
667 " A string corresponding to a path in $root_build_dir.\n" 674
668 "\n" 675 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" 676 {{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" 677 correspond to a path under "bundle_root_dir".
671 " This must correspond to a path under \"bundle_root_dir\".\n" 678
672 "\n" 679 See "gn help bundle_root_dir" for examples.
673 " See \"gn help bundle_root_dir\" for examples.\n"; 680 )";
674 681
675 const char kCflags[] = "cflags"; 682 const char kCflags[] = "cflags";
676 const char kCflags_HelpShort[] = 683 const char kCflags_HelpShort[] =
677 "cflags: [string list] Flags passed to all C compiler variants."; 684 "cflags: [string list] Flags passed to all C compiler variants.";
678 const char kCommonCflagsHelp[] = 685 const char kCommonCflagsHelp[] =
679 "cflags*: Flags passed to the C compiler.\n" 686 R"(cflags*: Flags passed to the C compiler.
680 "\n" 687
681 " A list of strings.\n" 688 A list of strings.
682 "\n" 689
683 " \"cflags\" are passed to all invocations of the C, C++, Objective C,\n" 690 "cflags" are passed to all invocations of the C, C++, Objective C, and
684 " and Objective C++ compilers.\n" 691 Objective C++ compilers.
685 "\n" 692
686 " To target one of these variants individually, use \"cflags_c\",\n" 693 To target one of these variants individually, use "cflags_c", "cflags_cc",
687 " \"cflags_cc\", \"cflags_objc\", and \"cflags_objcc\",\n" 694 "cflags_objc", and "cflags_objcc", respectively. These variant-specific
688 " respectively. These variant-specific versions of cflags* will be\n" 695 versions of cflags* will be appended on the compiler command line after
689 " appended on the compiler command line after \"cflags\".\n" 696 "cflags".
690 "\n" 697
691 " See also \"asmflags\" for flags for assembly-language files.\n" 698 See also "asmflags" for flags for assembly-language files.
699 )"
692 COMMON_ORDERING_HELP; 700 COMMON_ORDERING_HELP;
693 const char* kCflags_Help = kCommonCflagsHelp; 701 const char* kCflags_Help = kCommonCflagsHelp;
694 702
695 const char kAsmflags[] = "asmflags"; 703 const char kAsmflags[] = "asmflags";
696 const char kAsmflags_HelpShort[] = 704 const char kAsmflags_HelpShort[] =
697 "asmflags: [string list] Flags passed to the assembler."; 705 "asmflags: [string list] Flags passed to the assembler.";
698 const char* kAsmflags_Help = 706 const char* kAsmflags_Help =
699 "asmflags: Flags passed to the assembler.\n" 707 R"(asmflags: Flags passed to the assembler.
700 "\n" 708
701 " A list of strings.\n" 709 A list of strings.
702 "\n" 710
703 " \"asmflags\" are passed to any invocation of a tool that takes an\n" 711 "asmflags" are passed to any invocation of a tool that takes an .asm or .S
704 " .asm or .S file as input.\n" 712 file as input.
713 )"
705 COMMON_ORDERING_HELP; 714 COMMON_ORDERING_HELP;
706 715
707 const char kCflagsC[] = "cflags_c"; 716 const char kCflagsC[] = "cflags_c";
708 const char kCflagsC_HelpShort[] = 717 const char kCflagsC_HelpShort[] =
709 "cflags_c: [string list] Flags passed to the C compiler."; 718 "cflags_c: [string list] Flags passed to the C compiler.";
710 const char* kCflagsC_Help = kCommonCflagsHelp; 719 const char* kCflagsC_Help = kCommonCflagsHelp;
711 720
712 const char kCflagsCC[] = "cflags_cc"; 721 const char kCflagsCC[] = "cflags_cc";
713 const char kCflagsCC_HelpShort[] = 722 const char kCflagsCC_HelpShort[] =
714 "cflags_cc: [string list] Flags passed to the C++ compiler."; 723 "cflags_cc: [string list] Flags passed to the C++ compiler.";
715 const char* kCflagsCC_Help = kCommonCflagsHelp; 724 const char* kCflagsCC_Help = kCommonCflagsHelp;
716 725
717 const char kCflagsObjC[] = "cflags_objc"; 726 const char kCflagsObjC[] = "cflags_objc";
718 const char kCflagsObjC_HelpShort[] = 727 const char kCflagsObjC_HelpShort[] =
719 "cflags_objc: [string list] Flags passed to the Objective C compiler."; 728 "cflags_objc: [string list] Flags passed to the Objective C compiler.";
720 const char* kCflagsObjC_Help = kCommonCflagsHelp; 729 const char* kCflagsObjC_Help = kCommonCflagsHelp;
721 730
722 const char kCflagsObjCC[] = "cflags_objcc"; 731 const char kCflagsObjCC[] = "cflags_objcc";
723 const char kCflagsObjCC_HelpShort[] = 732 const char kCflagsObjCC_HelpShort[] =
724 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler."; 733 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler.";
725 const char* kCflagsObjCC_Help = kCommonCflagsHelp; 734 const char* kCflagsObjCC_Help = kCommonCflagsHelp;
726 735
727 const char kCheckIncludes[] = "check_includes"; 736 const char kCheckIncludes[] = "check_includes";
728 const char kCheckIncludes_HelpShort[] = 737 const char kCheckIncludes_HelpShort[] =
729 "check_includes: [boolean] Controls whether a target's files are checked."; 738 "check_includes: [boolean] Controls whether a target's files are checked.";
730 const char kCheckIncludes_Help[] = 739 const char kCheckIncludes_Help[] =
731 "check_includes: [boolean] Controls whether a target's files are checked.\n" 740 R"(check_includes: [boolean] Controls whether a target's files are checked.
732 "\n" 741
733 " When true (the default), the \"gn check\" command (as well as\n" 742 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" 743 --check flag) will check this target's sources and headers for proper
735 " and headers for proper dependencies.\n" 744 dependencies.
736 "\n" 745
737 " When false, the files in this target will be skipped by default.\n" 746 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" 747 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" 748 checking the includes of the current target's files.
740 "\n" 749
741 " If there are a few conditionally included headers that trip up\n" 750 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" 751 can exclude headers individually by annotating them with "nogncheck" (see "gn
743 " \"nogncheck\" (see \"gn help nogncheck\").\n" 752 help nogncheck").
744 "\n" 753
745 " The topic \"gn help check\" has general information on how checking\n" 754 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" 755 advice on how to pass a check in problematic cases.
747 "\n" 756
748 "Example\n" 757 Example
749 "\n" 758
750 " source_set(\"busted_includes\") {\n" 759 source_set("busted_includes") {
751 " # This target's includes are messed up, exclude it from checking.\n" 760 # This target's includes are messed up, exclude it from checking.
752 " check_includes = false\n" 761 check_includes = false
753 " ...\n" 762 ...
754 " }\n"; 763 }
764 )";
755 765
756 const char kCodeSigningArgs[] = "code_signing_args"; 766 const char kCodeSigningArgs[] = "code_signing_args";
757 const char kCodeSigningArgs_HelpShort[] = 767 const char kCodeSigningArgs_HelpShort[] =
758 "code_signing_args: [string list] Arguments passed to code signing script."; 768 "code_signing_args: [string list] Arguments passed to code signing script.";
759 const char kCodeSigningArgs_Help[] = 769 const char kCodeSigningArgs_Help[] =
760 "code_signing_args: [string list] Arguments passed to code signing " 770 R"(code_signing_args: [string list] Arguments passed to code signing script.
761 "script.\n" 771
762 "\n" 772 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" 773 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" 774 help source_expansion") to insert the source file names.
765 " expansion (see \"gn help source_expansion\") to insert the source file\n" 775
766 " names.\n" 776 See also "gn help create_bundle".
767 "\n" 777 )";
768 " See also \"gn help create_bundle\".\n";
769 778
770 const char kCodeSigningScript[] = "code_signing_script"; 779 const char kCodeSigningScript[] = "code_signing_script";
771 const char kCodeSigningScript_HelpShort[] = 780 const char kCodeSigningScript_HelpShort[] =
772 "code_signing_script: [file name] Script for code signing."; 781 "code_signing_script: [file name] Script for code signing.";
773 const char kCodeSigningScript_Help[] = 782 const char kCodeSigningScript_Help[] =
774 "code_signing_script: [file name] Script for code signing." 783 R"(code_signing_script: [file name] Script for code signing."
775 "\n" 784
776 " An absolute or buildfile-relative file name of a Python script to run\n" 785 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" 786 create_bundle target to perform code signing step.
778 "\n" 787
779 " See also \"gn help create_bundle\".\n"; 788 See also "gn help create_bundle".
789 )";
780 790
781 const char kCodeSigningSources[] = "code_signing_sources"; 791 const char kCodeSigningSources[] = "code_signing_sources";
782 const char kCodeSigningSources_HelpShort[] = 792 const char kCodeSigningSources_HelpShort[] =
783 "code_signing_sources: [file list] Sources for code signing step."; 793 "code_signing_sources: [file list] Sources for code signing step.";
784 const char kCodeSigningSources_Help[] = 794 const char kCodeSigningSources_Help[] =
785 "code_signing_sources: [file list] Sources for code signing step.\n" 795 R"(code_signing_sources: [file list] Sources for code signing step.
786 "\n" 796
787 " A list of files used as input for code signing script step of a\n" 797 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" 798 target. Non-absolute paths will be resolved relative to the current build
789 " the current build file.\n" 799 file.
790 "\n" 800
791 " See also \"gn help create_bundle\".\n"; 801 See also "gn help create_bundle".
802 )";
792 803
793 const char kCodeSigningOutputs[] = "code_signing_outputs"; 804 const char kCodeSigningOutputs[] = "code_signing_outputs";
794 const char kCodeSigningOutputs_HelpShort[] = 805 const char kCodeSigningOutputs_HelpShort[] =
795 "code_signing_outputs: [file list] Output files for code signing step."; 806 "code_signing_outputs: [file list] Output files for code signing step.";
796 const char kCodeSigningOutputs_Help[] = 807 const char kCodeSigningOutputs_Help[] =
797 "code_signing_outputs: [file list] Output files for code signing step.\n" 808 R"(code_signing_outputs: [file list] Output files for code signing step.
798 "\n" 809
799 " Outputs from the code signing step of a create_bundle target. Must\n" 810 Outputs from the code signing step of a create_bundle target. Must refer to
800 " refer to files in the build directory.\n" 811 files in the build directory.
801 "\n" 812
802 " See also \"gn help create_bundle\".\n"; 813 See also "gn help create_bundle".
814 )";
803 815
804 const char kCompleteStaticLib[] = "complete_static_lib"; 816 const char kCompleteStaticLib[] = "complete_static_lib";
805 const char kCompleteStaticLib_HelpShort[] = 817 const char kCompleteStaticLib_HelpShort[] =
806 "complete_static_lib: [boolean] Links all deps into a static library."; 818 "complete_static_lib: [boolean] Links all deps into a static library.";
807 const char kCompleteStaticLib_Help[] = 819 const char kCompleteStaticLib_Help[] =
808 "complete_static_lib: [boolean] Links all deps into a static library.\n" 820 R"(complete_static_lib: [boolean] Links all deps into a static library.
809 "\n" 821
810 " A static library normally doesn't include code from dependencies, but\n" 822 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" 823 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" 824 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" 825 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" 826 appears more than once in its dependency graph.
815 " graph.\n" 827
816 "\n" 828 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" 829 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" 830 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" 831 dependencies in one complete package. However, complete static libraries
820 " for all dependencies in one complete package. However, complete static\n" 832 themselves are never linked into other complete static libraries. All
821 " libraries themselves are never linked into other complete static\n" 833 complete static libraries are for distribution and linking them in would
822 " libraries. All complete static libraries are for distribution and\n" 834 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" 835 distribution, it should not be complete.
824 " static library is not for distribution, it should not be complete.\n" 836
825 "\n" 837 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" 838 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" 839 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" 840 "alink" rules.
829 " it easier to write \"alink\" rules.\n" 841
830 "\n" 842 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" 843 could be considered conceptually a member of both. libraries.
832 " target if it could be considered conceptually a member of both.\n" 844
833 " libraries.\n" 845 Example
834 "\n" 846
835 "Example\n" 847 static_library("foo") {
836 "\n" 848 complete_static_lib = true
837 " static_library(\"foo\") {\n" 849 deps = [ "bar" ]
838 " complete_static_lib = true\n" 850 }
839 " deps = [ \"bar\" ]\n" 851 )";
840 " }\n";
841 852
842 const char kConfigs[] = "configs"; 853 const char kConfigs[] = "configs";
843 const char kConfigs_HelpShort[] = 854 const char kConfigs_HelpShort[] =
844 "configs: [label list] Configs applying to this target or config."; 855 "configs: [label list] Configs applying to this target or config.";
845 const char kConfigs_Help[] = 856 const char kConfigs_Help[] =
846 "configs: Configs applying to this target or config.\n" 857 R"(configs: Configs applying to this target or config.
847 "\n" 858
848 " A list of config labels.\n" 859 A list of config labels.
849 "\n" 860
850 "Configs on a target\n" 861 Configs on a target
851 "\n" 862
852 " When used on a target, the include_dirs, defines, etc. in each config\n" 863 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" 864 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" 865 target. They will appear after the include_dirs, defines, etc. that the
855 " etc. that the target sets directly.\n" 866 target sets directly.
856 "\n" 867
857 " Since configs apply after the values set on a target, directly setting\n" 868 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" 869 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" 870 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" 871 config to the target's configs list.
861 "\n" 872
862 " The build configuration script will generally set up the default\n" 873 The build configuration script will generally set up the default configs
863 " configs applying to a given target type (see \"set_defaults\").\n" 874 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" 875 defined, it can add to or remove from this list.
865 " list.\n" 876
866 "\n" 877 Configs on a config
867 "Configs on a config\n" 878
868 "\n" 879 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" 880 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" 881 very large configs into more manageable named chunks.
871 " of settings from very large configs into more manageable named chunks.\n" 882
872 "\n" 883 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" 884 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" 885 else happens. This has some ramifications:
875 " *before* anything else happens. This has some ramifications:\n" 886
876 "\n" 887 - 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" 888 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" 889 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" 890 before the target is.
880 " not even be defined before the target is.\n" 891
881 "\n" 892 - 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" 893 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" 894 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" 895 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" 896 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" 897 complicates the implementation.)
887 " not normally relevant and complicates the implementation.)\n" 898 )"
888 COMMON_ORDERING_HELP 899 COMMON_ORDERING_HELP
889 "\n" 900 R"(
890 "Example\n" 901 Example
891 "\n" 902
892 " # Configs on a target.\n" 903 # Configs on a target.
893 " source_set(\"foo\") {\n" 904 source_set("foo") {
894 " # Don't use the default RTTI config that BUILDCONFIG applied to us.\n" 905 # Don't use the default RTTI config that BUILDCONFIG applied to us.
895 " configs -= [ \"//build:no_rtti\" ]\n" 906 configs -= [ "//build:no_rtti" ]
896 "\n" 907
897 " # Add some of our own settings.\n" 908 # Add some of our own settings.
898 " configs += [ \":mysettings\" ]\n" 909 configs += [ ":mysettings" ]
899 " }\n" 910 }
900 "\n" 911
901 " # Create a default_optimization config that forwards to one of a set\n" 912 # 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" 913 # 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" 914 # 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" 915 # specific set, while avoid duplicating the settings in two places.
905 " # two places.\n" 916 config("super_optimization") {
906 " config(\"super_optimization\") {\n" 917 cflags = [ ... ]
907 " cflags = [ ... ]\n" 918 }
908 " }\n" 919 config("default_optimization") {
909 " config(\"default_optimization\") {\n" 920 if (optimize_everything) {
910 " if (optimize_everything) {\n" 921 configs = [ ":super_optimization" ]
911 " configs = [ \":super_optimization\" ]\n" 922 } else {
912 " } else {\n" 923 configs = [ ":no_optimization" ]
913 " configs = [ \":no_optimization\" ]\n" 924 }
914 " }\n" 925 }
915 " }\n"; 926 )";
916 927
917 const char kConsole[] = "console"; 928 const char kConsole[] = "console";
918 const char kConsole_HelpShort[] = 929 const char kConsole_HelpShort[] =
919 "console: [boolean] Run this action in the console pool."; 930 "console: [boolean] Run this action in the console pool.";
920 const char kConsole_Help[] = 931 const char kConsole_Help[] =
921 "console: Run this action in the console pool.\n" 932 R"(console: Run this action in the console pool.
922 "\n" 933
923 " Boolean. Defaults to false.\n" 934 Boolean. Defaults to false.
924 "\n" 935
925 " Actions marked \"console = true\" will be run in the built-in ninja\n" 936 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" 937 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" 938 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" 939 logs, or actions that require user input.
929 " input.\n" 940
930 "\n" 941 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" 942 Ninja documentation on the console pool for more info.
932 " to the Ninja documentation on the console pool for more info.\n" 943
933 "\n" 944 Example
934 "Example\n" 945
935 "\n" 946 action("long_action_with_progress_logs") {
936 " action(\"long_action_with_progress_logs\") {\n" 947 console = true
937 " console = true\n" 948 }
938 " }\n"; 949 )";
939 950
940 const char kData[] = "data"; 951 const char kData[] = "data";
941 const char kData_HelpShort[] = 952 const char kData_HelpShort[] =
942 "data: [file list] Runtime data file dependencies."; 953 "data: [file list] Runtime data file dependencies.";
943 const char kData_Help[] = 954 const char kData_Help[] =
944 "data: Runtime data file dependencies.\n" 955 R"(data: Runtime data file dependencies.
945 "\n" 956
946 " Lists files or directories required to run the given target. These are\n" 957 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" 958 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" 959 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" 960 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" 961 input files to a script, use "inputs".
951 "\n" 962
952 " Appearing in the \"data\" section does not imply any special handling\n" 963 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" 964 copying them to the output directory. This is just used for declaring runtime
954 " declaring runtime dependencies. Runtime dependencies can be queried\n" 965 dependencies. Runtime dependencies can be queried using the "runtime_deps"
955 " using the \"runtime_deps\" category of \"gn desc\" or written during\n" 966 category of "gn desc" or written during build generation via
956 " build generation via \"--runtime-deps-list-file\".\n" 967 "--runtime-deps-list-file".
957 "\n" 968
958 " GN doesn't require data files to exist at build-time. So actions that\n" 969 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" 970 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" 971 both in the "outputs" list as well as the "data" list.
961 " list.\n" 972
962 "\n" 973 By convention, directories are listed with a trailing slash:
963 " By convention, directories are listed with a trailing slash:\n" 974 data = [ "test/data/" ]
964 " data = [ \"test/data/\" ]\n" 975 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" 976 paths are just rebased and passed along when requested.
966 " The paths are just rebased and passed along when requested.\n" 977
967 "\n" 978 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" 979 gathering data. See "gn help create_bundle" for details.
969 " into when gathering data. See \"gn help create_bundle\" for details.\n" 980
970 "\n" 981 See "gn help runtime_deps" for how these are used.
971 " See \"gn help runtime_deps\" for how these are used.\n"; 982 )";
972 983
973 const char kDataDeps[] = "data_deps"; 984 const char kDataDeps[] = "data_deps";
974 const char kDataDeps_HelpShort[] = 985 const char kDataDeps_HelpShort[] =
975 "data_deps: [label list] Non-linked dependencies."; 986 "data_deps: [label list] Non-linked dependencies.";
976 const char kDataDeps_Help[] = 987 const char kDataDeps_Help[] =
977 "data_deps: Non-linked dependencies.\n" 988 R"(data_deps: Non-linked dependencies.
978 "\n" 989
979 " A list of target labels.\n" 990 A list of target labels.
980 "\n" 991
981 " Specifies dependencies of a target that are not actually linked into\n" 992 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" 993 current target. Such dependencies will be built and will be available at
983 " available at runtime.\n" 994 runtime.
984 "\n" 995
985 " This is normally used for things like plugins or helper programs that\n" 996 This is normally used for things like plugins or helper programs that a
986 " a target needs at runtime.\n" 997 target needs at runtime.
987 "\n" 998
988 " Note: On iOS and OS X, create_bundle targets will not be recursed\n" 999 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" 1000 gathering data_deps. See "gn help create_bundle" for details.
990 " details.\n" 1001
991 "\n" 1002 See also "gn help deps" and "gn help data".
992 " See also \"gn help deps\" and \"gn help data\".\n" 1003
993 "\n" 1004 Example
994 "Example\n" 1005
995 "\n" 1006 executable("foo") {
996 " executable(\"foo\") {\n" 1007 deps = [ "//base" ]
997 " deps = [ \"//base\" ]\n" 1008 data_deps = [ "//plugins:my_runtime_plugin" ]
998 " data_deps = [ \"//plugins:my_runtime_plugin\" ]\n" 1009 }
999 " }\n"; 1010 )";
1000 1011
1001 const char kDefines[] = "defines"; 1012 const char kDefines[] = "defines";
1002 const char kDefines_HelpShort[] = 1013 const char kDefines_HelpShort[] =
1003 "defines: [string list] C preprocessor defines."; 1014 "defines: [string list] C preprocessor defines.";
1004 const char kDefines_Help[] = 1015 const char kDefines_Help[] =
1005 "defines: C preprocessor defines.\n" 1016 R"(defines: C preprocessor defines.
1006 "\n" 1017
1007 " A list of strings\n" 1018 A list of strings
1008 "\n" 1019
1009 " These strings will be passed to the C/C++ compiler as #defines. The\n" 1020 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" 1021 may or may not include an "=" to assign a value.
1022 )"
1011 COMMON_ORDERING_HELP 1023 COMMON_ORDERING_HELP
1012 "\n" 1024 R"(
1013 "Example\n" 1025 Example
1014 "\n" 1026
1015 " defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n"; 1027 defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
1028 )";
1016 1029
1017 const char kDepfile[] = "depfile"; 1030 const char kDepfile[] = "depfile";
1018 const char kDepfile_HelpShort[] = 1031 const char kDepfile_HelpShort[] =
1019 "depfile: [string] File name for input dependencies for actions."; 1032 "depfile: [string] File name for input dependencies for actions.";
1020 const char kDepfile_Help[] = 1033 const char kDepfile_Help[] =
1021 "depfile: [string] File name for input dependencies for actions.\n" 1034 R"(depfile: [string] File name for input dependencies for actions.
1022 "\n" 1035
1023 " If nonempty, this string specifies that the current action or\n" 1036 If nonempty, this string specifies that the current action or action_foreach
1024 " action_foreach target will generate the given \".d\" file containing\n" 1037 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" 1038 input. Empty or unset means that the script doesn't generate the files.
1026 " doesn't generate the files.\n" 1039
1027 "\n" 1040 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" 1041 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" 1042 specify only those dependencies not already included in sources or inputs.
1030 " depfiles should specify only those dependencies not already included\n" 1043
1031 " in sources or inputs.\n" 1044 The .d file should go in the target output directory. If you have more than
1032 "\n" 1045 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" 1046 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" 1047 according to the input."
1035 " the output file expansions described in \"gn help action_foreach\" to\n" 1048
1036 " name the .d file according to the input." 1049 The format is that of a Makefile and all paths must be relative to the root
1037 "\n" 1050 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" 1051 output of the action.
1039 " root build directory. Only one output may be listed and it must match\n" 1052
1040 " the first output of the action.\n" 1053 Although depfiles are created by an action, they should not be listed in the
1041 "\n" 1054 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" 1055
1043 " in the action's \"outputs\" unless another target will use the file as\n" 1056 Example
1044 " an input.\n" 1057
1045 "\n" 1058 action_foreach("myscript_target") {
1046 "Example\n" 1059 script = "myscript.py"
1047 "\n" 1060 sources = [ ... ]
1048 " action_foreach(\"myscript_target\") {\n" 1061
1049 " script = \"myscript.py\"\n" 1062 # Locate the depfile in the output directory named like the
1050 " sources = [ ... ]\n" 1063 # inputs but with a ".d" appended.
1051 "\n" 1064 depfile = "$relative_target_output_dir/{{source_name}}.d"
1052 " # Locate the depfile in the output directory named like the\n" 1065
1053 " # inputs but with a \".d\" appended.\n" 1066 # Say our script uses "-o <d file>" to indicate the depfile.
1054 " depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n" 1067 args = [ "{{source}}", "-o", depfile ]
1055 "\n" 1068 }
1056 " # Say our script uses \"-o <d file>\" to indicate the depfile.\n" 1069 )";
1057 " args = [ \"{{source}}\", \"-o\", depfile ]\n"
1058 " }\n";
1059 1070
1060 const char kDeps[] = "deps"; 1071 const char kDeps[] = "deps";
1061 const char kDeps_HelpShort[] = 1072 const char kDeps_HelpShort[] =
1062 "deps: [label list] Private linked dependencies."; 1073 "deps: [label list] Private linked dependencies.";
1063 const char kDeps_Help[] = 1074 const char kDeps_Help[] =
1064 "deps: Private linked dependencies.\n" 1075 R"(deps: Private linked dependencies.
1065 "\n" 1076
1066 " A list of target labels.\n" 1077 A list of target labels.
1067 "\n" 1078
1068 " Specifies private dependencies of a target. Private dependencies are\n" 1079 Specifies private dependencies of a target. Private dependencies are
1069 " propagated up the dependency tree and linked to dependant targets, but\n" 1080 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" 1081 grant the ability to include headers from the dependency. Public configs are
1071 " Public configs are not forwarded.\n" 1082 not forwarded.
1072 "\n" 1083
1073 "Details of dependency propagation\n" 1084 Details of dependency propagation
1074 "\n" 1085
1075 " Source sets, shared libraries, and non-complete static libraries\n" 1086 Source sets, shared libraries, and non-complete static libraries will be
1076 " will be propagated up the dependency tree across groups, non-complete\n" 1087 propagated up the dependency tree across groups, non-complete static
1077 " static libraries and source sets.\n" 1088 libraries and source sets.
1078 "\n" 1089
1079 " Executables, shared libraries, and complete static libraries will\n" 1090 Executables, shared libraries, and complete static libraries will link all
1080 " link all propagated targets and stop propagation. Actions and copy\n" 1091 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" 1092 propagation, allowing them to take a library as an input but not force
1082 " input but not force dependants to link to it.\n" 1093 dependants to link to it.
1083 "\n" 1094
1084 " Propagation of all_dependent_configs and public_configs happens\n" 1095 Propagation of all_dependent_configs and public_configs happens independently
1085 " independently of target type. all_dependent_configs are always\n" 1096 of target type. all_dependent_configs are always propagated across all types
1086 " propagated across all types of targets, and public_configs\n" 1097 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" 1098 all types of targets.
1088 "\n" 1099
1089 " Data dependencies are propagated differently. See\n" 1100 Data dependencies are propagated differently. See "gn help data_deps" and
1090 " \"gn help data_deps\" and \"gn help runtime_deps\".\n" 1101 "gn help runtime_deps".
1091 "\n" 1102
1092 " See also \"public_deps\".\n"; 1103 See also "public_deps".
1104 )";
1093 1105
1094 const char kIncludeDirs[] = "include_dirs"; 1106 const char kIncludeDirs[] = "include_dirs";
1095 const char kIncludeDirs_HelpShort[] = 1107 const char kIncludeDirs_HelpShort[] =
1096 "include_dirs: [directory list] Additional include directories."; 1108 "include_dirs: [directory list] Additional include directories.";
1097 const char kIncludeDirs_Help[] = 1109 const char kIncludeDirs_Help[] =
1098 "include_dirs: Additional include directories.\n" 1110 R"(include_dirs: Additional include directories.
1099 "\n" 1111
1100 " A list of source directories.\n" 1112 A list of source directories.
1101 "\n" 1113
1102 " The directories in this list will be added to the include path for\n" 1114 The directories in this list will be added to the include path for the files
1103 " the files in the affected target.\n" 1115 in the affected target.
1116 )"
1104 COMMON_ORDERING_HELP 1117 COMMON_ORDERING_HELP
1105 "\n" 1118 R"(
1106 "Example\n" 1119 Example
1107 "\n" 1120
1108 " include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n"; 1121 include_dirs = [ "src/include", "//third_party/foo" ]
1122 )";
1109 1123
1110 const char kInputs[] = "inputs"; 1124 const char kInputs[] = "inputs";
1111 const char kInputs_HelpShort[] = 1125 const char kInputs_HelpShort[] =
1112 "inputs: [file list] Additional compile-time dependencies."; 1126 "inputs: [file list] Additional compile-time dependencies.";
1113 const char kInputs_Help[] = 1127 const char kInputs_Help[] =
1114 "inputs: Additional compile-time dependencies.\n" 1128 R"(inputs: Additional compile-time dependencies.
1115 "\n" 1129
1116 " Inputs are compile-time dependencies of the current target. This means\n" 1130 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" 1131 all inputs must be available before compiling any of the sources or executing
1118 " or executing any actions.\n" 1132 any actions.
1119 "\n" 1133
1120 " Inputs are typically only used for action and action_foreach targets.\n" 1134 Inputs are typically only used for action and action_foreach targets.
1121 "\n" 1135
1122 "Inputs for actions\n" 1136 Inputs for actions
1123 "\n" 1137
1124 " For action and action_foreach targets, inputs should be the inputs to\n" 1138 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" 1139 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" 1140 imports (the main script itself will be an implicit dependency of the action
1127 "\n" 1141 so need not be listed).
1128 " of the action so need not be listed).\n" 1142
1129 "\n" 1143 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" 1144 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" 1145 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" 1146 sources.
1133 " by the script (if any) in sources.\n" 1147
1134 "\n" 1148 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" 1149 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" 1150 dynamically write input dependencies, that might not be known until actually
1137 " allows the script to dynamically write input dependencies, that might\n" 1151 executing the script. This is more efficient than doing processing while
1138 " not be known until actually executing the script. This is more\n" 1152 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" 1153 hardcoding the list.
1140 " inputs, and is easier to keep in-sync than hardcoding the list.\n" 1154
1141 "\n" 1155 Script input gotchas
1142 "Script input gotchas\n" 1156
1143 "\n" 1157 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" 1158 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" 1159 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" 1160 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" 1161
1148 " dependencies will be broken.\n" 1162 The problem happens if a file is ever removed because the inputs are not
1149 "\n" 1163 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" 1164 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" 1165 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" 1166 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" 1167 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" 1168 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" 1169
1156 " listed in the inputs, the build will detect when it has changed in any\n" 1170 Inputs for binary targets
1157 " way and the action will re-run.\n" 1171
1158 "\n" 1172 Any input dependencies will be resolved before compiling any sources.
1159 "Inputs for binary targets\n" 1173 Normally, all actions that a target depends on will be run before any files
1160 "\n" 1174 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" 1175 typically need to list them in the inputs section.
1162 " Normally, all actions that a target depends on will be run before any\n" 1176
1163 " files in a target are compiled. So if you depend on generated headers,\n" 1177 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" 1178 that changes in any of the inputs will force all sources in the target to be
1165 "\n" 1179 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" 1180 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" 1181
1168 " the target to be recompiled. If an input only applies to a subset of\n" 1182 Example
1169 " source files, you may want to split those into a separate target to\n" 1183
1170 " avoid unnecessary recompiles.\n" 1184 action("myscript") {
1171 "\n" 1185 script = "domything.py"
1172 "Example\n" 1186 inputs = [ "input.data" ]
1173 "\n" 1187 }
1174 " action(\"myscript\") {\n" 1188 )";
1175 " script = \"domything.py\"\n"
1176 " inputs = [ \"input.data\" ]\n"
1177 " }\n";
1178 1189
1179 const char kLdflags[] = "ldflags"; 1190 const char kLdflags[] = "ldflags";
1180 const char kLdflags_HelpShort[] = 1191 const char kLdflags_HelpShort[] =
1181 "ldflags: [string list] Flags passed to the linker."; 1192 "ldflags: [string list] Flags passed to the linker.";
1182 const char kLdflags_Help[] = 1193 const char kLdflags_Help[] =
1183 "ldflags: Flags passed to the linker.\n" 1194 R"(ldflags: Flags passed to the linker.
1184 "\n" 1195
1185 " A list of strings.\n" 1196 A list of strings.
1186 "\n" 1197
1187 " These flags are passed on the command-line to the linker and generally\n" 1198 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" 1199 specify various linking options. Most targets will not need these and will
1189 " will use \"libs\" and \"lib_dirs\" instead.\n" 1200 use "libs" and "lib_dirs" instead.
1190 "\n" 1201
1191 " ldflags are NOT pushed to dependents, so applying ldflags to source\n" 1202 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" 1203 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" 1204 targets, put them in a config and set it in the all_dependent_configs or
1194 " all_dependent_configs or public_configs.\n" 1205 public_configs.
1206 )"
1195 COMMON_ORDERING_HELP; 1207 COMMON_ORDERING_HELP;
1196 1208
1197 #define COMMON_LIB_INHERITANCE_HELP \ 1209 #define COMMON_LIB_INHERITANCE_HELP \
1198 "\n" \ 1210 "\n" \
1199 " libs and lib_dirs work differently than other flags in two respects.\n" \ 1211 " 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" \ 1212 " First, then are inherited across static library boundaries until a\n" \
1201 " shared library or executable target is reached. Second, they are\n" \ 1213 " 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" \ 1214 " uniquified so each one is only passed once (the first instance of it\n" \
1203 " will be the one used).\n" 1215 " will be the one used).\n"
1204 1216
1205 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \ 1217 #define LIBS_AND_LIB_DIRS_ORDERING_HELP \
1206 "\n" \ 1218 "\n" \
1207 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \ 1219 " For \"libs\" and \"lib_dirs\" only, the values propagated from\n" \
1208 " dependencies (as described above) are applied last assuming they\n" \ 1220 " dependencies (as described above) are applied last assuming they\n" \
1209 " are not already in the list.\n" 1221 " are not already in the list.\n"
1210 1222
1211 const char kLibDirs[] = "lib_dirs"; 1223 const char kLibDirs[] = "lib_dirs";
1212 const char kLibDirs_HelpShort[] = 1224 const char kLibDirs_HelpShort[] =
1213 "lib_dirs: [directory list] Additional library directories."; 1225 "lib_dirs: [directory list] Additional library directories.";
1214 const char kLibDirs_Help[] = 1226 const char kLibDirs_Help[] =
1215 "lib_dirs: Additional library directories.\n" 1227 R"(lib_dirs: Additional library directories.
1216 "\n" 1228
1217 " A list of directories.\n" 1229 A list of directories.
1218 "\n" 1230
1219 " Specifies additional directories passed to the linker for searching\n" 1231 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" 1232 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" 1233 being relative to the current build file.
1234 )"
1222 COMMON_LIB_INHERITANCE_HELP 1235 COMMON_LIB_INHERITANCE_HELP
1223 COMMON_ORDERING_HELP 1236 COMMON_ORDERING_HELP
1224 LIBS_AND_LIB_DIRS_ORDERING_HELP 1237 LIBS_AND_LIB_DIRS_ORDERING_HELP
1225 "\n" 1238 R"(
1226 "Example\n" 1239 Example
1227 "\n" 1240
1228 " lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n"; 1241 lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
1242 )";
1229 1243
1230 const char kLibs[] = "libs"; 1244 const char kLibs[] = "libs";
1231 const char kLibs_HelpShort[] = 1245 const char kLibs_HelpShort[] =
1232 "libs: [string list] Additional libraries to link."; 1246 "libs: [string list] Additional libraries to link.";
1233 const char kLibs_Help[] = 1247 const char kLibs_Help[] =
1234 "libs: Additional libraries to link.\n" 1248 R"(libs: Additional libraries to link.
1235 "\n" 1249
1236 " A list of library names or library paths.\n" 1250 A list of library names or library paths.
1237 "\n" 1251
1238 " These libraries will be linked into the final binary (executable or\n" 1252 These libraries will be linked into the final binary (executable or shared
1239 " shared library) containing the current target.\n" 1253 library) containing the current target.
1254 )"
1240 COMMON_LIB_INHERITANCE_HELP 1255 COMMON_LIB_INHERITANCE_HELP
1241 "\n" 1256 R"(
1242 "Types of libs\n" 1257 Types of libs
1243 "\n" 1258
1244 " There are several different things that can be expressed in libs:\n" 1259 There are several different things that can be expressed in libs:
1245 "\n" 1260
1246 " File paths\n" 1261 File paths
1247 " Values containing '/' will be treated as references to files in\n" 1262 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" 1263 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" 1264 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" 1265 for libraries that are checked in to the version control. For libraries
1251 " version control. For libraries that are generated by the build,\n" 1266 that are generated by the build, use normal GN deps to link them.
1252 " use normal GN deps to link them.\n" 1267
1253 "\n" 1268 System libraries
1254 " System libraries\n" 1269 Values not containing '/' will be treated as system library names. These
1255 " Values not containing '/' will be treated as system library names.\n" 1270 will be passed unmodified to the linker and prefixed with the
1256 " These will be passed unmodified to the linker and prefixed with\n" 1271 "lib_prefix" attribute of the linker tool. Generally you would set the
1257 " the \"lib_prefix\" attribute of the linker tool. Generally you\n" 1272 "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" 1273 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" 1274 of the tool.
1260 " will be encoded in the \"lib_prefix\" of the tool.\n" 1275
1261 "\n" 1276 Apple frameworks
1262 " Apple frameworks\n" 1277 System libraries ending in ".framework" will be special-cased: the switch
1263 " System libraries ending in \".framework\" will be special-cased:\n" 1278 "-framework" will be prepended instead of the lib_prefix, and the
1264 " the switch \"-framework\" will be prepended instead of the\n" 1279 ".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" 1280 framework dependencies.
1266 " to support the way Mac links framework dependencies.\n" 1281 )"
1267 COMMON_ORDERING_HELP 1282 COMMON_ORDERING_HELP
1268 LIBS_AND_LIB_DIRS_ORDERING_HELP 1283 LIBS_AND_LIB_DIRS_ORDERING_HELP
1269 "\n" 1284 R"(
1270 "Examples\n" 1285 Examples
1271 "\n" 1286
1272 " On Windows:\n" 1287 On Windows:
1273 " libs = [ \"ctl3d.lib\" ]\n" 1288 libs = [ "ctl3d.lib" ]
1274 "\n" 1289
1275 " On Linux:\n" 1290 On Linux:
1276 " libs = [ \"ld\" ]\n"; 1291 libs = [ "ld" ]
1292 )";
1277 1293
1278 const char kOutputExtension[] = "output_extension"; 1294 const char kOutputExtension[] = "output_extension";
1279 const char kOutputExtension_HelpShort[] = 1295 const char kOutputExtension_HelpShort[] =
1280 "output_extension: [string] Value to use for the output's file extension."; 1296 "output_extension: [string] Value to use for the output's file extension.";
1281 const char kOutputExtension_Help[] = 1297 const char kOutputExtension_Help[] =
1282 "output_extension: Value to use for the output's file extension.\n" 1298 R"(output_extension: Value to use for the output's file extension.
1283 "\n" 1299
1284 " Normally the file extension for a target is based on the target\n" 1300 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" 1301 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" 1302 example to use "libfreetype.so.6" instead of libfreetype.so on Linux).
1287 " of libfreetype.so on Linux).\n" 1303
1288 "\n" 1304 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" 1305 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" 1306 extension will be used.
1291 " output extension will be used.\n" 1307
1292 "\n" 1308 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" 1309 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" 1310 "gn help tool".
1295 " output file name. See \"gn help tool\".\n" 1311
1296 "\n" 1312 Example
1297 "Example\n" 1313
1298 "\n" 1314 shared_library("freetype") {
1299 " shared_library(\"freetype\") {\n" 1315 if (is_linux) {
1300 " if (is_linux) {\n" 1316 # Call the output "libfreetype.so.6"
1301 " # Call the output \"libfreetype.so.6\"\n" 1317 output_extension = "so.6"
1302 " output_extension = \"so.6\"\n" 1318 }
1303 " }\n" 1319 ...
1304 " ...\n" 1320 }
1305 " }\n" 1321
1306 "\n" 1322 # On Windows, generate a "mysettings.cpl" control panel applet. Control panel
1307 " # On Windows, generate a \"mysettings.cpl\" control panel applet.\n" 1323 # applets are actually special shared libraries.
1308 " # Control panel applets are actually special shared libraries.\n" 1324 if (is_win) {
1309 " if (is_win) {\n" 1325 shared_library("mysettings") {
1310 " shared_library(\"mysettings\") {\n" 1326 output_extension = "cpl"
1311 " output_extension = \"cpl\"\n" 1327 ...
1312 " ...\n" 1328 }
1313 " }\n" 1329 }
1314 " }\n"; 1330 )";
1315 1331
1316 const char kOutputDir[] = "output_dir"; 1332 const char kOutputDir[] = "output_dir";
1317 const char kOutputDir_HelpShort[] = 1333 const char kOutputDir_HelpShort[] =
1318 "output_dir: [directory] Directory to put output file in."; 1334 "output_dir: [directory] Directory to put output file in.";
1319 const char kOutputDir_Help[] = 1335 const char kOutputDir_Help[] =
1320 "output_dir: [directory] Directory to put output file in.\n" 1336 R"(output_dir: [directory] Directory to put output file in.
1321 "\n" 1337
1322 " For library and executable targets, overrides the directory for the\n" 1338 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" 1339 output. This must be in the root_build_dir or a child thereof.
1324 "\n" 1340
1325 " This should generally be in the root_out_dir or a subdirectory thereof\n" 1341 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" 1342 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" 1343 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" 1344 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" 1345 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" 1346 target is only present in one toolchain.
1331 "\n" 1347
1332 " Normally the toolchain specifies the output directory for libraries\n" 1348 Normally the toolchain specifies the output directory for libraries and
1333 " and executables (see \"gn help tool\"). You will have to consult that\n" 1349 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" 1350 default location. The default location will be used if output_dir is
1335 " output_dir is undefined or empty.\n" 1351 undefined or empty.
1336 "\n" 1352
1337 "Example\n" 1353 Example
1338 "\n" 1354
1339 " shared_library(\"doom_melon\") {\n" 1355 shared_library("doom_melon") {
1340 " output_dir = \"$root_out_dir/plugin_libs\"\n" 1356 output_dir = "$root_out_dir/plugin_libs"
1341 " ...\n" 1357 ...
1342 " }\n"; 1358 }
1359 )";
1343 1360
1344 const char kOutputName[] = "output_name"; 1361 const char kOutputName[] = "output_name";
1345 const char kOutputName_HelpShort[] = 1362 const char kOutputName_HelpShort[] =
1346 "output_name: [string] Name for the output file other than the default."; 1363 "output_name: [string] Name for the output file other than the default.";
1347 const char kOutputName_Help[] = 1364 const char kOutputName_Help[] =
1348 "output_name: Define a name for the output file other than the default.\n" 1365 R"(output_name: Define a name for the output file other than the default.
1349 "\n" 1366
1350 " Normally the output name of a target will be based on the target name,\n" 1367 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" 1368 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" 1369 "bar_unittests.exe" (using Windows as an example).
1353 "\n" 1370
1354 " Sometimes you will want an alternate name to avoid collisions or\n" 1371 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" 1372 internal name isn't appropriate for public distribution.
1356 "\n" 1373
1357 " The output name should have no extension or prefixes, these will be\n" 1374 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" 1375 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" 1376 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" 1377 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" 1378 flexibility, create a copy target to produce the file you want.
1362 " to produce the file you want.\n" 1379
1363 "\n" 1380 This variable is valid for all binary output target types.
1364 " This variable is valid for all binary output target types.\n" 1381
1365 "\n" 1382 Example
1366 "Example\n" 1383
1367 "\n" 1384 static_library("doom_melon") {
1368 " static_library(\"doom_melon\") {\n" 1385 output_name = "fluffy_bunny"
1369 " output_name = \"fluffy_bunny\"\n" 1386 }
1370 " }\n"; 1387 )";
1371 1388
1372 const char kOutputPrefixOverride[] = "output_prefix_override"; 1389 const char kOutputPrefixOverride[] = "output_prefix_override";
1373 const char kOutputPrefixOverride_HelpShort[] = 1390 const char kOutputPrefixOverride_HelpShort[] =
1374 "output_prefix_override: [boolean] Don't use prefix for output name."; 1391 "output_prefix_override: [boolean] Don't use prefix for output name.";
1375 const char kOutputPrefixOverride_Help[] = 1392 const char kOutputPrefixOverride_Help[] =
1376 "output_prefix_override: Don't use prefix for output name.\n" 1393 R"(output_prefix_override: Don't use prefix for output name.
1377 "\n" 1394
1378 " A boolean that overrides the output prefix for a target. Defaults to\n" 1395 A boolean that overrides the output prefix for a target. Defaults to false.
1379 " false.\n" 1396
1380 "\n" 1397 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" 1398 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" 1399
1383 " named \"foo\".\n" 1400 The output prefix for a given target type is specified on the linker tool
1384 "\n" 1401 (see "gn help tool"). Sometimes this prefix is undesired.
1385 " The output prefix for a given target type is specified on the linker\n" 1402
1386 " tool (see \"gn help tool\"). Sometimes this prefix is undesired.\n" 1403 See also "gn help output_extension".
1387 "\n" 1404
1388 " See also \"gn help output_extension\".\n" 1405 Example
1389 "\n" 1406
1390 "Example\n" 1407 shared_library("doom_melon") {
1391 "\n" 1408 # Normally this will produce "libdoom_melon.so" on Linux. Setting this flag
1392 " shared_library(\"doom_melon\") {\n" 1409 # will produce "doom_melon.so".
1393 " # Normally this will produce \"libdoom_melon.so\" on Linux, setting\n" 1410 output_prefix_override = true
1394 " # Setting this flag will produce \"doom_melon.so\".\n" 1411 ...
1395 " output_prefix_override = true\n" 1412 })";
1396 " ...\n"
1397 " }\n";
1398 1413
1399 const char kOutputs[] = "outputs"; 1414 const char kOutputs[] = "outputs";
1400 const char kOutputs_HelpShort[] = 1415 const char kOutputs_HelpShort[] =
1401 "outputs: [file list] Output files for actions and copy targets."; 1416 "outputs: [file list] Output files for actions and copy targets.";
1402 const char kOutputs_Help[] = 1417 const char kOutputs_Help[] =
1403 "outputs: Output files for actions and copy targets.\n" 1418 R"(outputs: Output files for actions and copy targets.
1404 "\n" 1419
1405 " Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n" 1420 Outputs is valid for "copy", "action", and "action_foreach" target types and
1406 " target types and indicates the resulting files. Outputs must always\n" 1421 indicates the resulting files. Outputs must always refer to files in the
1407 " refer to files in the build directory.\n" 1422 build directory.
1408 "\n" 1423
1409 " copy\n" 1424 copy
1410 " Copy targets should have exactly one entry in the outputs list. If\n" 1425 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" 1426 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" 1427 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" 1428 map a single input name to a single output name. See "gn help copy".
1414 " output name. See \"gn help copy\".\n" 1429
1415 "\n" 1430 action_foreach
1416 " action_foreach\n" 1431 Action_foreach targets must always use source expansions to map input files
1417 " Action_foreach targets must always use source expansions to map\n" 1432 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" 1433 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" 1434 the name of the input file). See "gn help action_foreach".
1420 " files (presumably based on the name of the input file). See\n" 1435
1421 " \"gn help action_foreach\".\n" 1436 action
1422 "\n" 1437 Action targets (excluding action_foreach) must list literal output file(s)
1423 " action\n" 1438 with no source expansions. See "gn help action".
1424 " Action targets (excluding action_foreach) must list literal output\n" 1439 )";
1425 " file(s) with no source expansions. See \"gn help action\".\n";
1426 1440
1427 const char kPrecompiledHeader[] = "precompiled_header"; 1441 const char kPrecompiledHeader[] = "precompiled_header";
1428 const char kPrecompiledHeader_HelpShort[] = 1442 const char kPrecompiledHeader_HelpShort[] =
1429 "precompiled_header: [string] Header file to precompile."; 1443 "precompiled_header: [string] Header file to precompile.";
1430 const char kPrecompiledHeader_Help[] = 1444 const char kPrecompiledHeader_Help[] =
1431 "precompiled_header: [string] Header file to precompile.\n" 1445 R"(precompiled_header: [string] Header file to precompile.
1432 "\n" 1446
1433 " Precompiled headers will be used when a target specifies this\n" 1447 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" 1448 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" 1449 corresponding to the source files must also specify precompiled headers (see
1436 " specify precompiled headers (see \"gn help tool\"). The tool\n" 1450 "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" 1451 to use.
1438 "\n" 1452
1439 " The precompiled header/source variables can be specified on a target\n" 1453 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" 1454 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" 1455 a target can only have one precompiled header.
1442 "\n" 1456
1443 "MSVC precompiled headers\n" 1457 MSVC precompiled headers
1444 "\n" 1458
1445 " When using MSVC-style precompiled headers, the \"precompiled_header\"\n" 1459 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" 1460 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" 1461 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" 1462 #include line in source code. The compiler will match this string against
1449 " match this string against includes or forced includes (/FI).\n" 1463 includes or forced includes (/FI).
1450 "\n" 1464
1451 " MSVC also requires a source file to compile the header with. This must\n" 1465 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" 1466 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" 1467 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" 1468 make the .pch file used for subsequent compiles.
1455 "\n" 1469
1456 " If you use both C and C++ sources, the precompiled header and source\n" 1470 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" 1471 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" 1472 includes in __cplusplus #ifdefs so the file will compile in C mode.
1459 " in C mode.\n" 1473
1460 "\n" 1474 For example, if the toolchain specifies MSVC headers:
1461 " For example, if the toolchain specifies MSVC headers:\n" 1475
1462 "\n" 1476 toolchain("vc_x64") {
1463 " toolchain(\"vc_x64\") {\n" 1477 ...
1464 " ...\n" 1478 tool("cxx") {
1465 " tool(\"cxx\") {\n" 1479 precompiled_header_type = "msvc"
1466 " precompiled_header_type = \"msvc\"\n" 1480 ...
1467 " ...\n" 1481
1468 "\n" 1482 You might make a config like this:
1469 " You might make a config like this:\n" 1483
1470 "\n" 1484 config("use_precompiled_headers") {
1471 " config(\"use_precompiled_headers\") {\n" 1485 precompiled_header = "build/precompile.h"
1472 " precompiled_header = \"build/precompile.h\"\n" 1486 precompiled_source = "//build/precompile.cc"
1473 " precompiled_source = \"//build/precompile.cc\"\n" 1487
1474 "\n" 1488 # Either your source files should #include "build/precompile.h"
1475 " # Either your source files should #include \"build/precompile.h\"\n" 1489 # first, or you can do this to force-include the header.
1476 " # first, or you can do this to force-include the header.\n" 1490 cflags = [ "/FI$precompiled_header" ]
1477 " cflags = [ \"/FI$precompiled_header\" ]\n" 1491 }
1478 " }\n" 1492
1479 "\n" 1493 And then define a target that uses the config:
1480 " And then define a target that uses the config:\n" 1494
1481 "\n" 1495 executable("doom_melon") {
1482 " executable(\"doom_melon\") {\n" 1496 configs += [ ":use_precompiled_headers" ]
1483 " configs += [ \":use_precompiled_headers\" ]\n" 1497 ...
1484 " ...\n" 1498 )";
1485 "\n";
1486 1499
1487 const char kPrecompiledSource[] = "precompiled_source"; 1500 const char kPrecompiledSource[] = "precompiled_source";
1488 const char kPrecompiledSource_HelpShort[] = 1501 const char kPrecompiledSource_HelpShort[] =
1489 "precompiled_source: [file name] Source file to precompile."; 1502 "precompiled_source: [file name] Source file to precompile.";
1490 const char kPrecompiledSource_Help[] = 1503 const char kPrecompiledSource_Help[] =
1491 "precompiled_source: [file name] Source file to precompile.\n" 1504 R"(precompiled_source: [file name] Source file to precompile.
1492 "\n" 1505
1493 " The source file that goes along with the precompiled_header when\n" 1506 The source file that goes along with the precompiled_header when using
1494 " using \"msvc\"-style precompiled headers. It will be implicitly added\n" 1507 "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"; 1508 of the target. See "gn help precompiled_header".
1509 )";
1496 1510
1497 const char kProductType[] = "product_type"; 1511 const char kProductType[] = "product_type";
1498 const char kProductType_HelpShort[] = 1512 const char kProductType_HelpShort[] =
1499 "product_type: [string] Product type for Xcode projects."; 1513 "product_type: [string] Product type for Xcode projects.";
1500 const char kProductType_Help[] = 1514 const char kProductType_Help[] =
1501 "product_type: Product type for Xcode projects.\n" 1515 R"(product_type: Product type for Xcode projects.
1502 "\n" 1516
1503 " Correspond to the type of the product of a create_bundle target. Only\n" 1517 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" 1518 meaningful to Xcode (used as part of the Xcode project generation).
1505 "\n" 1519
1506 " When generating Xcode project files, only create_bundle target with\n" 1520 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" 1521 non-empty product_type will have a corresponding target in Xcode project.
1508 " project.\n"; 1522 )";
1509 1523
1510 const char kPublic[] = "public"; 1524 const char kPublic[] = "public";
1511 const char kPublic_HelpShort[] = 1525 const char kPublic_HelpShort[] =
1512 "public: [file list] Declare public header files for a target."; 1526 "public: [file list] Declare public header files for a target.";
1513 const char kPublic_Help[] = 1527 const char kPublic_Help[] =
1514 "public: Declare public header files for a target.\n" 1528 R"(public: Declare public header files for a target.
1515 "\n" 1529
1516 " A list of files that other targets can include. These permissions are\n" 1530 A list of files that other targets can include. These permissions are checked
1517 " checked via the \"check\" command (see \"gn help check\").\n" 1531 via the "check" command (see "gn help check").
1518 "\n" 1532
1519 " If no public files are declared, other targets (assuming they have\n" 1533 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" 1534 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" 1535 variable is defined on a target, dependent targets may only include files on
1522 " targets may only include files on this whitelist.\n" 1536 this whitelist.
1523 "\n" 1537
1524 " Header file permissions are also subject to visibility. A target\n" 1538 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" 1539 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" 1540 headers indicate which subset of those files are permitted. See "gn help
1527 " permitted. See \"gn help visibility\" for more.\n" 1541 visibility" for more.
1528 "\n" 1542
1529 " Public files are inherited through the dependency tree. So if there is\n" 1543 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" 1544 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" 1545 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" 1546 include will be rejected.
1533 "\n" 1547
1534 " GN only knows about files declared in the \"sources\" and \"public\"\n" 1548 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" 1549 targets. If a file is included that is not known to the build, it will be
1536 " build, it will be allowed.\n" 1550 allowed.
1537 "\n" 1551
1538 "Examples\n" 1552 Examples
1539 "\n" 1553
1540 " These exact files are public:\n" 1554 These exact files are public:
1541 " public = [ \"foo.h\", \"bar.h\" ]\n" 1555 public = [ "foo.h", "bar.h" ]
1542 "\n" 1556
1543 " No files are public (no targets may include headers from this one):\n" 1557 No files are public (no targets may include headers from this one):
1544 " public = []\n"; 1558 public = []
1559 )";
1545 1560
1546 const char kPublicConfigs[] = "public_configs"; 1561 const char kPublicConfigs[] = "public_configs";
1547 const char kPublicConfigs_HelpShort[] = 1562 const char kPublicConfigs_HelpShort[] =
1548 "public_configs: [label list] Configs applied to dependents."; 1563 "public_configs: [label list] Configs applied to dependents.";
1549 const char kPublicConfigs_Help[] = 1564 const char kPublicConfigs_Help[] =
1550 "public_configs: Configs to be applied on dependents.\n" 1565 R"(public_configs: Configs to be applied on dependents.
1551 "\n" 1566
1552 " A list of config labels.\n" 1567 A list of config labels.
1553 "\n" 1568
1554 " Targets directly depending on this one will have the configs listed in\n" 1569 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" 1570 variable added to them. These configs will also apply to the current target.
1556 " current target.\n" 1571
1557 "\n" 1572 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" 1573 dependencies have been resolved. Therefore, a target will not see these
1559 " dependencies have been resolved. Therefore, a target will not see\n" 1574 force-added configs in their "configs" variable while the script is running,
1560 " these force-added configs in their \"configs\" variable while the\n" 1575 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" 1576 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" 1577 target's headers.
1563 " directories necessary to compile a target's headers.\n" 1578
1564 "\n" 1579 See also "all_dependent_configs".
1565 " See also \"all_dependent_configs\".\n" 1580 )"
1566 COMMON_ORDERING_HELP; 1581 COMMON_ORDERING_HELP;
1567 1582
1568 const char kPublicDeps[] = "public_deps"; 1583 const char kPublicDeps[] = "public_deps";
1569 const char kPublicDeps_HelpShort[] = 1584 const char kPublicDeps_HelpShort[] =
1570 "public_deps: [label list] Declare public dependencies."; 1585 "public_deps: [label list] Declare public dependencies.";
1571 const char kPublicDeps_Help[] = 1586 const char kPublicDeps_Help[] =
1572 "public_deps: Declare public dependencies.\n" 1587 R"(public_deps: Declare public dependencies.
1573 "\n" 1588
1574 " Public dependencies are like private dependencies (see\n" 1589 Public dependencies are like private dependencies (see "gn help deps") but
1575 " \"gn help deps\") but additionally express that the current target\n" 1590 additionally express that the current target exposes the listed deps as part
1576 " exposes the listed deps as part of its public API.\n" 1591 of its public API.
1577 "\n" 1592
1578 " This has several ramifications:\n" 1593 This has several ramifications:
1579 "\n" 1594
1580 " - public_configs that are part of the dependency are forwarded\n" 1595 - public_configs that are part of the dependency are forwarded to direct
1581 " to direct dependents.\n" 1596 dependents.
1582 "\n" 1597
1583 " - Public headers in the dependency are usable by dependents\n" 1598 - Public headers in the dependency are usable by dependents (includes do
1584 " (includes do not require a direct dependency or visibility).\n" 1599 not require a direct dependency or visibility).
1585 "\n" 1600
1586 " - If the current target is a shared library, other shared libraries\n" 1601 - If the current target is a shared library, other shared libraries that it
1587 " that it publicly depends on (directly or indirectly) are\n" 1602 publicly depends on (directly or indirectly) are propagated up the
1588 " propagated up the dependency tree to dependents for linking.\n" 1603 dependency tree to dependents for linking.
1589 "\n" 1604
1590 "Discussion\n" 1605 Discussion
1591 "\n" 1606
1592 " Say you have three targets: A -> B -> C. C's visibility may allow\n" 1607 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" 1608 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" 1609 from C, and C's public_configs would apply only to B.
1595 " only to B.\n" 1610
1596 "\n" 1611 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" 1612 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" 1613
1599 " headers.\n" 1614 Generally if you are writing a target B and you include C's headers as part
1600 "\n" 1615 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" 1616 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" 1617
1603 " consider B and C to be part of a unit, you should use public_deps\n" 1618 Example
1604 " instead of deps.\n" 1619
1605 "\n" 1620 # This target can include files from "c" but not from
1606 "Example\n" 1621 # "super_secret_implementation_details".
1607 "\n" 1622 executable("a") {
1608 " # This target can include files from \"c\" but not from\n" 1623 deps = [ ":b" ]
1609 " # \"super_secret_implementation_details\".\n" 1624 }
1610 " executable(\"a\") {\n" 1625
1611 " deps = [ \":b\" ]\n" 1626 shared_library("b") {
1612 " }\n" 1627 deps = [ ":super_secret_implementation_details" ]
1613 "\n" 1628 public_deps = [ ":c" ]
1614 " shared_library(\"b\") {\n" 1629 }
1615 " deps = [ \":super_secret_implementation_details\" ]\n" 1630 )";
1616 " public_deps = [ \":c\" ]\n"
1617 " }\n";
1618 1631
1619 const char kResponseFileContents[] = "response_file_contents"; 1632 const char kResponseFileContents[] = "response_file_contents";
1620 const char kResponseFileContents_HelpShort[] = 1633 const char kResponseFileContents_HelpShort[] =
1621 "response_file_contents: [string list] Contents of .rsp file for actions."; 1634 "response_file_contents: [string list] Contents of .rsp file for actions.";
1622 const char kResponseFileContents_Help[] = 1635 const char kResponseFileContents_Help[] =
1623 "response_file_contents: Contents of a response file for actions.\n" 1636 R"*(response_file_contents: Contents of a response file for actions.
1624 "\n" 1637
1625 " Sometimes the arguments passed to a script can be too long for the\n" 1638 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" 1639 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" 1640 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" 1641 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" 1642 action or action_foreach target.
1630 "\n" 1643
1631 " If the response_file_contents variable is defined and non-empty, the\n" 1644 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" 1645 will be treated as script args (including possibly substitution patterns)
1633 " patterns) that will be written to a temporary file at build time.\n" 1646 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" 1647 temporary file will be substituted for "{{response_file_name}}" in the script
1635 " \"{{response_file_name}}\" in the script args.\n" 1648 args.
1636 "\n" 1649
1637 " The response file contents will always be quoted and escaped\n" 1650 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" 1651 Unix shell rules. To parse the response file, the Python script should use
1639 " script should use \"shlex.split(file_contents)\".\n" 1652 "shlex.split(file_contents)".
1640 "\n" 1653
1641 "Example\n" 1654 Example
1642 "\n" 1655
1643 " action(\"process_lots_of_files\") {\n" 1656 action("process_lots_of_files") {
1644 " script = \"process.py\",\n" 1657 script = "process.py",
1645 " inputs = [ ... huge list of files ... ]\n" 1658 inputs = [ ... huge list of files ... ]
1646 "\n" 1659
1647 " # Write all the inputs to a response file for the script. Also,\n" 1660 # Write all the inputs to a response file for the script. Also,
1648 " # make the paths relative to the script working directory.\n" 1661 # make the paths relative to the script working directory.
1649 " response_file_contents = rebase_path(inputs, root_build_dir)\n" 1662 response_file_contents = rebase_path(inputs, root_build_dir)
1650 "\n" 1663
1651 " # The script expects the name of the response file in --file-list.\n" 1664 # The script expects the name of the response file in --file-list.
1652 " args = [\n" 1665 args = [
1653 " \"--enable-foo\",\n" 1666 "--enable-foo",
1654 " \"--file-list={{response_file_name}}\",\n" 1667 "--file-list={{response_file_name}}",
1655 " ]\n" 1668 ]
1656 " }\n"; 1669 }
1670 )*";
1657 1671
1658 const char kScript[] = "script"; 1672 const char kScript[] = "script";
1659 const char kScript_HelpShort[] = 1673 const char kScript_HelpShort[] =
1660 "script: [file name] Script file for actions."; 1674 "script: [file name] Script file for actions.";
1661 const char kScript_Help[] = 1675 const char kScript_Help[] =
1662 "script: Script file for actions.\n" 1676 R"(script: Script file for actions.
1663 "\n" 1677
1664 " An absolute or buildfile-relative file name of a Python script to run\n" 1678 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" 1679 action and action_foreach targets (see "gn help action" and "gn help
1666 " \"gn help action_foreach\").\n"; 1680 action_foreach").
1681 )";
1667 1682
1668 const char kSources[] = "sources"; 1683 const char kSources[] = "sources";
1669 const char kSources_HelpShort[] = 1684 const char kSources_HelpShort[] =
1670 "sources: [file list] Source files for a target."; 1685 "sources: [file list] Source files for a target.";
1671 const char kSources_Help[] = 1686 const char kSources_Help[] =
1672 "sources: Source files for a target\n" 1687 R"(sources: Source files for a target
1673 "\n" 1688
1674 " A list of files. Non-absolute paths will be resolved relative to the\n" 1689 A list of files. Non-absolute paths will be resolved relative to the current
1675 " current build file.\n" 1690 build file.
1676 "\n" 1691
1677 "Sources for binary targets\n" 1692 Sources for binary targets
1678 "\n" 1693
1679 " For binary targets (source sets, executables, and libraries), the\n" 1694 For binary targets (source sets, executables, and libraries), the known file
1680 " known file types will be compiled with the associated tools. Unknown\n" 1695 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" 1696 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" 1697 so GN knows about the existance of those files for the purposes of include
1683 " files for the purposes of include checking.\n" 1698 checking.
1684 "\n" 1699
1685 " As a special case, a file ending in \".def\" will be treated as a\n" 1700 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" 1701 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" 1702 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" 1703 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" 1704 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" 1705 library they're linked into).
1691 "\n" 1706
1692 "Sources for non-binary targets\n" 1707 Sources for non-binary targets
1693 "\n" 1708
1694 " action_foreach\n" 1709 action_foreach
1695 " The sources are the set of files that the script will be executed\n" 1710 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" 1711 script will run once per file.
1697 "\n" 1712
1698 " action\n" 1713 action
1699 " The sources will be treated the same as inputs. See " 1714 The sources will be treated the same as inputs. See "gn help inputs" for
1700 "\"gn help inputs\"\n" 1715 more information and usage advice.
1701 " for more information and usage advice.\n" 1716
1702 "\n" 1717 copy
1703 " copy\n" 1718 The source are the source files to copy.
1704 " The source are the source files to copy.\n"; 1719 )";
1705 1720
1706 const char kTestonly[] = "testonly"; 1721 const char kTestonly[] = "testonly";
1707 const char kTestonly_HelpShort[] = 1722 const char kTestonly_HelpShort[] =
1708 "testonly: [boolean] Declares a target must only be used for testing."; 1723 "testonly: [boolean] Declares a target must only be used for testing.";
1709 const char kTestonly_Help[] = 1724 const char kTestonly_Help[] =
1710 "testonly: Declares a target must only be used for testing.\n" 1725 R"(testonly: Declares a target must only be used for testing.
1711 "\n" 1726
1712 " Boolean. Defaults to false.\n" 1727 Boolean. Defaults to false.
1713 "\n" 1728
1714 " When a target is marked \"testonly = true\", it must only be depended\n" 1729 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" 1730 other test-only targets. Otherwise, GN will issue an error that the
1716 " that the depenedency is not allowed.\n" 1731 depenedency is not allowed.
1717 "\n" 1732
1718 " This feature is intended to prevent accidentally shipping test code\n" 1733 This feature is intended to prevent accidentally shipping test code in a
1719 " in a final product.\n" 1734 final product.
1720 "\n" 1735
1721 "Example\n" 1736 Example
1722 "\n" 1737
1723 " source_set(\"test_support\") {\n" 1738 source_set("test_support") {
1724 " testonly = true\n" 1739 testonly = true
1725 " ...\n" 1740 ...
1726 " }\n"; 1741 }
1742 )";
1727 1743
1728 const char kVisibility[] = "visibility"; 1744 const char kVisibility[] = "visibility";
1729 const char kVisibility_HelpShort[] = 1745 const char kVisibility_HelpShort[] =
1730 "visibility: [label list] A list of labels that can depend on a target."; 1746 "visibility: [label list] A list of labels that can depend on a target.";
1731 const char kVisibility_Help[] = 1747 const char kVisibility_Help[] =
1732 "visibility: A list of labels that can depend on a target.\n" 1748 R"(visibility: A list of labels that can depend on a target.
1733 "\n" 1749
1734 " A list of labels and label patterns that define which targets can\n" 1750 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" 1751 the current one. These permissions are checked via the "check" command (see
1736 " \"check\" command (see \"gn help check\").\n" 1752 "gn help check").
1737 "\n" 1753
1738 " If visibility is not defined, it defaults to public (\"*\").\n" 1754 If visibility is not defined, it defaults to public ("*").
1739 "\n" 1755
1740 " If visibility is defined, only the targets with labels that match it\n" 1756 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" 1757 depend on the current target. The empty list means no targets can depend on
1742 " can depend on the current target.\n" 1758 the current target.
1743 "\n" 1759
1744 " Tip: Often you will want the same visibility for all targets in a\n" 1760 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" 1761 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" 1762 target, and the targets will inherit that scope and see the definition.
1747 " the definition.\n" 1763
1748 "\n" 1764 Patterns
1749 "Patterns\n" 1765
1750 "\n" 1766 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" 1767 supported. If a toolchain is specified, only targets in that toolchain will
1752 " patterns are supported. If a toolchain is specified, only targets\n" 1768 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" 1769 toolchains will be matched.
1754 " a pattern, targets in all toolchains will be matched.\n" 1770
1755 "\n" 1771 Examples
1756 "Examples\n" 1772
1757 "\n" 1773 Only targets in the current buildfile ("private"):
1758 " Only targets in the current buildfile (\"private\"):\n" 1774 visibility = [ ":*" ]
1759 " visibility = [ \":*\" ]\n" 1775
1760 "\n" 1776 No targets (used for targets that should be leaf nodes):
1761 " No targets (used for targets that should be leaf nodes):\n" 1777 visibility = []
1762 " visibility = []\n" 1778
1763 "\n" 1779 Any target ("public", the default):
1764 " Any target (\"public\", the default):\n" 1780 visibility = [ "*" ]
1765 " visibility = [ \"*\" ]\n" 1781
1766 "\n" 1782 All targets in the current directory and any subdirectory:
1767 " All targets in the current directory and any subdirectory:\n" 1783 visibility = [ "./*" ]
1768 " visibility = [ \"./*\" ]\n" 1784
1769 "\n" 1785 Any target in "//bar/BUILD.gn":
1770 " Any target in \"//bar/BUILD.gn\":\n" 1786 visibility = [ "//bar:*" ]
1771 " visibility = [ \"//bar:*\" ]\n" 1787
1772 "\n" 1788 Any target in "//bar/" or any subdirectory thereof:
1773 " Any target in \"//bar/\" or any subdirectory thereof:\n" 1789 visibility = [ "//bar/*" ]
1774 " visibility = [ \"//bar/*\" ]\n" 1790
1775 "\n" 1791 Just these specific targets:
1776 " Just these specific targets:\n" 1792 visibility = [ ":mything", "//foo:something_else" ]
1777 " visibility = [ \":mything\", \"//foo:something_else\" ]\n" 1793
1778 "\n" 1794 Any target in the current directory and any subdirectory thereof, plus
1779 " Any target in the current directory and any subdirectory thereof, plus\n" 1795 any targets in "//bar/" and any subdirectory thereof.
1780 " any targets in \"//bar/\" and any subdirectory thereof.\n" 1796 visibility = [ "./*", "//bar/*" ]
1781 " visibility = [ \"./*\", \"//bar/*\" ]\n"; 1797 )";
1782 1798
1783 const char kWriteRuntimeDeps[] = "write_runtime_deps"; 1799 const char kWriteRuntimeDeps[] = "write_runtime_deps";
1784 const char kWriteRuntimeDeps_HelpShort[] = 1800 const char kWriteRuntimeDeps_HelpShort[] =
1785 "write_runtime_deps: Writes the target's runtime_deps to the given path."; 1801 "write_runtime_deps: Writes the target's runtime_deps to the given path.";
1786 const char kWriteRuntimeDeps_Help[] = 1802 const char kWriteRuntimeDeps_Help[] =
1787 "write_runtime_deps: Writes the target's runtime_deps to the given path.\n" 1803 R"(write_runtime_deps: Writes the target's runtime_deps to the given path.
1788 "\n" 1804
1789 " Does not synchronously write the file, but rather schedules it\n" 1805 Does not synchronously write the file, but rather schedules it to be written
1790 " to be written at the end of generation.\n" 1806 at the end of generation.
1791 "\n" 1807
1792 " If the file exists and the contents are identical to that being\n" 1808 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" 1809 file will not be updated. This will prevent unnecessary rebuilds of targets
1794 " rebuilds of targets that depend on this file.\n" 1810 that depend on this file.
1795 "\n" 1811
1796 " Path must be within the output directory.\n" 1812 Path must be within the output directory.
1797 "\n" 1813
1798 " See \"gn help runtime_deps\" for how the runtime dependencies are\n" 1814 See "gn help runtime_deps" for how the runtime dependencies are computed.
1799 " computed.\n" 1815
1800 "\n" 1816 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" 1817 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" 1818 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" 1819 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" 1820 help --runtime-deps-list-file").
1805 " the command line (see \"gn help --runtime-deps-list-file\").\n"; 1821 )";
1806 1822
1807 // ----------------------------------------------------------------------------- 1823 // -----------------------------------------------------------------------------
1808 1824
1809 VariableInfo::VariableInfo() 1825 VariableInfo::VariableInfo()
1810 : help_short(""), 1826 : help_short(""),
1811 help("") { 1827 help("") {
1812 } 1828 }
1813 1829
1814 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help) 1830 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help)
1815 : help_short(in_help_short), 1831 : help_short(in_help_short),
(...skipping 80 matching lines...) Expand 10 before | Expand all | Expand 10 after
1896 INSERT_VARIABLE(Testonly) 1912 INSERT_VARIABLE(Testonly)
1897 INSERT_VARIABLE(Visibility) 1913 INSERT_VARIABLE(Visibility)
1898 INSERT_VARIABLE(WriteRuntimeDeps) 1914 INSERT_VARIABLE(WriteRuntimeDeps)
1899 } 1915 }
1900 return info_map; 1916 return info_map;
1901 } 1917 }
1902 1918
1903 #undef INSERT_VARIABLE 1919 #undef INSERT_VARIABLE
1904 1920
1905 } // namespace variables 1921 } // namespace variables
OLDNEW
« tools/gn/function_template.cc ('K') | « tools/gn/switches.cc ('k') | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698