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
3 // found in the LICENSE file.
5 #include "tools/gn/functions.h"
7 #include "tools/gn/config_values_generator.h"
8 #include "tools/gn/err.h"
9 #include "tools/gn/parse_tree.h"
10 #include "tools/gn/scope.h"
11 #include "tools/gn/target_generator.h"
12 #include "tools/gn/value.h"
13 #include "tools/gn/variables.h"
15 #define DEPENDENT_CONFIG_VARS \
16 " Dependent configs: all_dependent_configs, direct_dependent_configs\n"
18 " Deps: data, datadeps, deps, forward_dependent_configs_from, hard_dep\n"
19 #define GENERAL_TARGET_VARS \
20 " General: configs, source_prereqs, sources\n"
26 Value
ExecuteGenericTarget(const char* target_type
,
28 const FunctionCallNode
* function
,
29 const std::vector
<Value
>& args
,
32 if (!EnsureNotProcessingImport(function
, scope
, err
) ||
33 !EnsureNotProcessingBuildConfig(function
, scope
, err
))
35 Scope
block_scope(scope
);
36 if (!FillTargetBlockScope(scope
, function
, target_type
, block
,
37 args
, &block_scope
, err
))
40 block
->ExecuteBlockInScope(&block_scope
, err
);
44 TargetGenerator::GenerateTarget(&block_scope
, function
, args
,
49 block_scope
.CheckForUnusedVars(err
);
55 // action ----------------------------------------------------------------------
57 // Common help paragraph on script runtime execution directories.
58 #define SCRIPT_EXECUTION_CONTEXT \
59 " The script will be executed with the given arguments with the current\n"\
60 " directory being that of the root build directory. If you pass files\n"\
61 " to your script, see \"gn help rebase_path\" for how to convert\n" \
62 " file names to be relative to the build directory (file names in the\n" \
63 " sources, outputs, and source_prereqs will be all treated as relative\n" \
64 " to the current build file and converted as needed automatically).\n"
66 // Common help paragraph on script output directories.
67 #define SCRIPT_EXECUTION_OUTPUTS \
68 " All output files must be inside the output directory of the build.\n" \
69 " You would generally use |$target_out_dir| or |$target_gen_dir| to\n" \
70 " reference the output or generated intermediate file directories,\n" \
74 " The \"deps\" for an action will always be completed before any part\n" \
75 " of the action is run so it can depend on the output of previous\n" \
76 " steps. The \"datadeps\" will be built if the action is built, but\n" \
77 " may not have completed before all steps of the action are started.\n" \
78 " This can give additional parallelism in the build for runtime-only\n" \
81 const char kAction
[] = "action";
82 const char kAction_HelpShort
[] =
83 "action: Declare a target that runs a script a single time.";
84 const char kAction_Help
[] =
85 "action: Declare a target that runs a script a single time.\n"
87 " This target type allows you to run a script a single time to produce\n"
88 " or more output files. If you want to run a script once for each of a\n"
89 " set of input files, see \"gn help action_foreach\".\n"
93 " In an action the \"sources\" and \"source_prereqs\" are treated the\n"
94 " same: they're both input dependencies on script execution with no\n"
95 " special handling. If you want to pass the sources to your script, you\n"
96 " must do so explicitly by including them in the \"args\". Note also\n"
97 " that this means there is no special handling of paths since GN\n"
98 " doesn't know which of the args are paths and not. You will want to use\n"
99 " rebase_path() to convert paths to be relative to the root_build_dir.\n"
101 " It is recommended you put inputs to your script in the \"sources\"\n"
102 " variable, and stuff like other Python files required to run your\n"
103 " script in the \"source_prereqs\" variable.\n"
109 " You should specify files created by your script by specifying them in\n"
110 " the \"outputs\".\n"
112 SCRIPT_EXECUTION_CONTEXT
114 "File name handling\n"
116 SCRIPT_EXECUTION_OUTPUTS
120 " args, data, datadeps, depfile, deps, outputs*, script*,\n"
121 " source_prereqs, sources\n"
126 " action(\"run_this_guy_once\") {\n"
127 " script = \"doprocessing.py\"\n"
128 " sources = [ \"my_configuration.txt\" ]\n"
129 " outputs = [ \"$target_gen_dir/insightful_output.txt\" ]\n"
131 " # Our script imports this Python file so we want to rebuild if it\n"
133 " source_prereqs = [ \"helper_library.py\" ]\n"
135 " # Note that we have to manually pass the sources to our script if\n"
136 " # the script needs them as inputs.\n"
137 " args = [ \"--out\", rebase_path(target_gen_dir, root_build_dir) ] +\n"
138 " rebase_path(sources, root_build_dir)\n"
141 Value
RunAction(Scope
* scope
,
142 const FunctionCallNode
* function
,
143 const std::vector
<Value
>& args
,
146 return ExecuteGenericTarget(functions::kAction
, scope
, function
, args
,
150 // action_foreach --------------------------------------------------------------
152 const char kActionForEach
[] = "action_foreach";
153 const char kActionForEach_HelpShort
[] =
154 "action_foreach: Declare a target that runs a script over a set of files.";
155 const char kActionForEach_Help
[] =
156 "action_foreach: Declare a target that runs a script over a set of files.\n"
158 " This target type allows you to run a script once-per-file over a set\n"
159 " of sources. If you want to run a script once that takes many files as\n"
160 " input, see \"gn help action\".\n"
164 " The script will be run once per file in the \"sources\" variable. The\n"
165 " \"outputs\" variable should specify one or more files with a source\n"
166 " expansion pattern in it (see \"gn help source_expansion\"). The output\n"
167 " file(s) for each script invocation should be unique. Normally you\n"
168 " use \"{{source_name_part}}\" in each output file.\n"
170 " If your script takes additional data as input, such as a shared\n"
171 " configuration file or a Python module it uses, those files should be\n"
172 " listed in the \"source_prereqs\" variable. These files are treated as\n"
173 " dependencies of each script invocation.\n"
179 SCRIPT_EXECUTION_CONTEXT
181 "File name handling\n"
183 SCRIPT_EXECUTION_OUTPUTS
187 " args, data, datadeps, depfile, deps, outputs*, script*,\n"
188 " source_prereqs, sources*\n"
193 " # Runs the script over each IDL file. The IDL script will generate\n"
194 " # both a .cc and a .h file for each input.\n"
195 " action_foreach(\"my_idl\") {\n"
196 " script = \"idl_processor.py\"\n"
197 " sources = [ \"foo.idl\", \"bar.idl\" ]\n"
199 " # Our script reads this file each time, so we need to list is as a\n"
200 " # dependency so we can rebuild if it changes.\n"
201 " source_prereqs = [ \"my_configuration.txt\" ]\n"
203 " # Transformation from source file name to output file names.\n"
204 " outputs = [ \"$target_gen_dir/{{source_name_part}}.h\",\n"
205 " \"$target_gen_dir/{{source_name_part}}.cc\" ]\n"
207 " # Note that since \"args\" is opaque to GN, if you specify paths\n"
208 " # here, you will need to convert it to be relative to the build\n"
209 " # directory using \"rebase_path()\".\n"
213 " rebase_path(relative_target_gen_dir, root_build_dir) +\n"
214 " \"/{{source_name_part}}.h\" ]\n"
217 Value
RunActionForEach(Scope
* scope
,
218 const FunctionCallNode
* function
,
219 const std::vector
<Value
>& args
,
222 return ExecuteGenericTarget(functions::kActionForEach
, scope
, function
, args
,
226 // component -------------------------------------------------------------------
228 const char kComponent
[] = "component";
229 const char kComponent_HelpShort
[] =
230 "component: Declare a component target.";
231 const char kComponent_Help
[] =
232 "component: Declare a component target.\n"
234 " A component is a shared library, static library, or source set\n"
235 " depending on the component mode. This allows a project to separate\n"
236 " out a build into shared libraries for faster development (link time is\n"
237 " reduced) but to switch to a static build for releases (for better\n"
240 " To use this function you must set the value of the \"component_mode\"\n"
241 " variable to one of the following strings:\n"
242 " - \"shared_library\"\n"
243 " - \"static_library\"\n"
244 " - \"source_set\"\n"
245 " It is an error to call \"component\" without defining the mode\n"
246 " (typically this is done in the master build configuration file).\n";
248 Value
RunComponent(Scope
* scope
,
249 const FunctionCallNode
* function
,
250 const std::vector
<Value
>& args
,
253 // A component is either a shared or static library, depending on the value
254 // of |component_mode|.
255 const Value
* component_mode_value
=
256 scope
->GetValue(variables::kComponentMode
);
258 static const char helptext
[] =
259 "You're declaring a component here but have not defined "
260 "\"component_mode\" to\neither \"shared_library\" or \"static_library\".";
261 if (!component_mode_value
) {
262 *err
= Err(function
->function(), "No component mode set.", helptext
);
265 if (component_mode_value
->type() != Value::STRING
||
266 (component_mode_value
->string_value() != functions::kSharedLibrary
&&
267 component_mode_value
->string_value() != functions::kStaticLibrary
&&
268 component_mode_value
->string_value() != functions::kSourceSet
)) {
269 *err
= Err(function
->function(), "Invalid component mode set.", helptext
);
272 const std::string
& component_mode
= component_mode_value
->string_value();
274 if (!EnsureNotProcessingImport(function
, scope
, err
))
276 Scope
block_scope(scope
);
277 if (!FillTargetBlockScope(scope
, function
, component_mode
.c_str(), block
,
278 args
, &block_scope
, err
))
281 block
->ExecuteBlockInScope(&block_scope
, err
);
282 if (err
->has_error())
285 TargetGenerator::GenerateTarget(&block_scope
, function
, args
,
286 component_mode
, err
);
290 // copy ------------------------------------------------------------------------
292 const char kCopy
[] = "copy";
293 const char kCopy_HelpShort
[] =
294 "copy: Declare a target that copies files.";
295 const char kCopy_Help
[] =
296 "copy: Declare a target that copies files.\n"
298 "File name handling\n"
300 " All output files must be inside the output directory of the build.\n"
301 " You would generally use |$target_out_dir| or |$target_gen_dir| to\n"
302 " reference the output or generated intermediate file directories,\n"
305 " Both \"sources\" and \"outputs\" must be specified. Sources can\n"
306 " as many files as you want, but there can only be one item in the\n"
307 " outputs list (plural is used for the name for consistency with\n"
308 " other target types).\n"
310 " If there is more than one source file, your output name should specify\n"
311 " a mapping from each source files to output file names using source\n"
312 " expansion (see \"gn help source_expansion\"). The placeholders will\n"
313 " will look like \"{{source_name_part}}\", for example.\n"
317 " # Write a rule that copies a checked-in DLL to the output directory.\n"
318 " copy(\"mydll\") {\n"
319 " sources = [ \"mydll.dll\" ]\n"
320 " outputs = [ \"$target_out_dir/mydll.dll\" ]\n"
323 " # Write a rule to copy several files to the target generated files\n"
325 " copy(\"myfiles\") {\n"
326 " sources = [ \"data1.dat\", \"data2.dat\", \"data3.dat\" ]\n"
328 " # Use source expansion to generate output files with the\n"
329 " # corresponding file names in the gen dir. This will just copy each\n"
331 " outputs = [ \"$target_gen_dir/{{source_file_part}}\" ]\n"
334 Value
RunCopy(const FunctionCallNode
* function
,
335 const std::vector
<Value
>& args
,
338 if (!EnsureNotProcessingImport(function
, scope
, err
) ||
339 !EnsureNotProcessingBuildConfig(function
, scope
, err
))
341 TargetGenerator::GenerateTarget(scope
, function
, args
, functions::kCopy
, err
);
345 // executable ------------------------------------------------------------------
347 const char kExecutable
[] = "executable";
348 const char kExecutable_HelpShort
[] =
349 "executable: Declare an executable target.";
350 const char kExecutable_Help
[] =
351 "executable: Declare an executable target.\n"
355 CONFIG_VALUES_VARS_HELP
357 DEPENDENT_CONFIG_VARS
360 Value
RunExecutable(Scope
* scope
,
361 const FunctionCallNode
* function
,
362 const std::vector
<Value
>& args
,
365 return ExecuteGenericTarget(functions::kExecutable
, scope
, function
, args
,
369 // group -----------------------------------------------------------------------
371 const char kGroup
[] = "group";
372 const char kGroup_HelpShort
[] =
373 "group: Declare a named group of targets.";
374 const char kGroup_Help
[] =
375 "group: Declare a named group of targets.\n"
377 " This target type allows you to create meta-targets that just collect a\n"
378 " set of dependencies into one named target. Groups can additionally\n"
379 " specify configs that apply to their dependents.\n"
381 " Depending on a group is exactly like depending directly on that\n"
382 " group's deps. Direct dependent configs will get automatically\n"
383 " forwarded through the group so you shouldn't need to use\n"
384 " \"forward_dependent_configs_from.\n"
389 DEPENDENT_CONFIG_VARS
393 " group(\"all\") {\n"
395 " \"//project:runner\",\n"
396 " \"//project:unit_tests\",\n"
400 Value
RunGroup(Scope
* scope
,
401 const FunctionCallNode
* function
,
402 const std::vector
<Value
>& args
,
405 return ExecuteGenericTarget(functions::kGroup
, scope
, function
, args
,
409 // shared_library --------------------------------------------------------------
411 const char kSharedLibrary
[] = "shared_library";
412 const char kSharedLibrary_HelpShort
[] =
413 "shared_library: Declare a shared library target.";
414 const char kSharedLibrary_Help
[] =
415 "shared_library: Declare a shared library target.\n"
417 " A shared library will be specified on the linker line for targets\n"
418 " listing the shared library in its \"deps\". If you don't want this\n"
419 " (say you dynamically load the library at runtime), then you should\n"
420 " depend on the shared library via \"datadeps\" instead.\n"
424 CONFIG_VALUES_VARS_HELP
426 DEPENDENT_CONFIG_VARS
429 Value
RunSharedLibrary(Scope
* scope
,
430 const FunctionCallNode
* function
,
431 const std::vector
<Value
>& args
,
434 return ExecuteGenericTarget(functions::kSharedLibrary
, scope
, function
, args
,
438 // source_set ------------------------------------------------------------------
440 extern const char kSourceSet
[] = "source_set";
441 extern const char kSourceSet_HelpShort
[] =
442 "source_set: Declare a source set target.";
443 extern const char kSourceSet_Help
[] =
444 "source_set: Declare a source set target.\n"
446 " A source set is a collection of sources that get compiled, but are not\n"
447 " linked to produce any kind of library. Instead, the resulting object\n"
448 " files are implicitly added to the linker line of all targets that\n"
449 " depend on the source set.\n"
451 " In most cases, a source set will behave like a static library, except\n"
452 " no actual library file will be produced. This will make the build go\n"
453 " a little faster by skipping creation of a large static library, while\n"
454 " maintaining the organizational benefits of focused build targets.\n"
456 " The main difference between a source set and a static library is\n"
457 " around handling of exported symbols. Most linkers assume declaring\n"
458 " a function exported means exported from the static library. The linker\n"
459 " can then do dead code elimination to delete code not reachable from\n"
460 " exported functions.\n"
462 " A source set will not do this code elimination since there is no link\n"
463 " step. This allows you to link many sources sets into a shared library\n"
464 " and have the \"exported symbol\" notation indicate \"export from the\n"
465 " final shared library and not from the intermediate targets.\" There is\n"
466 " no way to express this concept when linking multiple static libraries\n"
467 " into a shared library.\n"
471 CONFIG_VALUES_VARS_HELP
473 DEPENDENT_CONFIG_VARS
476 Value
RunSourceSet(Scope
* scope
,
477 const FunctionCallNode
* function
,
478 const std::vector
<Value
>& args
,
481 return ExecuteGenericTarget(functions::kSourceSet
, scope
, function
, args
,
485 // static_library --------------------------------------------------------------
487 const char kStaticLibrary
[] = "static_library";
488 const char kStaticLibrary_HelpShort
[] =
489 "static_library: Declare a static library target.";
490 const char kStaticLibrary_Help
[] =
491 "static_library: Declare a static library target.\n"
493 " Make a \".a\" / \".lib\" file.\n"
495 " If you only need the static library for intermediate results in the\n"
496 " build, you should consider a source_set instead since it will skip\n"
497 " the (potentially slow) step of creating the intermediate library file.\n"
501 CONFIG_VALUES_VARS_HELP
503 DEPENDENT_CONFIG_VARS
506 Value
RunStaticLibrary(Scope
* scope
,
507 const FunctionCallNode
* function
,
508 const std::vector
<Value
>& args
,
511 return ExecuteGenericTarget(functions::kStaticLibrary
, scope
, function
, args
,
515 // test ------------------------------------------------------------------------
517 const char kTest
[] = "test";
518 const char kTest_HelpShort
[] =
519 "test: Declares a test target.";
520 const char kTest_Help
[] =
521 "test: Declares a test target.\n"
523 " This is like an executable target, but is named differently to make\n"
524 " the purpose of the target more obvious. It's possible in the future\n"
525 " we can do some enhancements like \"list all of the tests in a given\n"
528 " See \"gn help executable\" for usage.\n";
530 Value
RunTest(Scope
* scope
,
531 const FunctionCallNode
* function
,
532 const std::vector
<Value
>& args
,
535 return ExecuteGenericTarget(functions::kExecutable
, scope
, function
, args
,
539 } // namespace functions