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