// Copyright (c) 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include "tools/gn/functions.h"
#include "tools/gn/config_values_generator.h"
#include "tools/gn/err.h"
#include "tools/gn/parse_tree.h"
#include "tools/gn/scope.h"
#include "tools/gn/target_generator.h"
#include "tools/gn/value.h"
#include "tools/gn/variables.h"
#define DEPENDENT_CONFIG_VARS \
" Dependent configs: all_dependent_configs, direct_dependent_configs\n"
#define DEPS_VARS \
" Deps: data, datadeps, deps, forward_dependent_configs_from, hard_dep\n"
#define GENERAL_TARGET_VARS \
" General: configs, inputs, sources\n"
namespace functions {
namespace {
Value ExecuteGenericTarget(const char* target_type,
Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
if (!EnsureNotProcessingImport(function, scope, err) ||
!EnsureNotProcessingBuildConfig(function, scope, err))
return Value();
Scope block_scope(scope);
if (!FillTargetBlockScope(scope, function, target_type, block,
args, &block_scope, err))
return Value();
block->ExecuteBlockInScope(&block_scope, err);
if (err->has_error())
return Value();
TargetGenerator::GenerateTarget(&block_scope, function, args,
target_type, err);
if (err->has_error())
return Value();
block_scope.CheckForUnusedVars(err);
return Value();
}
} // namespace
// action ----------------------------------------------------------------------
// Common help paragraph on script runtime execution directories.
#define SCRIPT_EXECUTION_CONTEXT \
" The script will be executed with the given arguments with the current\n"\
" directory being that of the root build directory. If you pass files\n"\
" to your script, see \"gn help rebase_path\" for how to convert\n" \
" file names to be relative to the build directory (file names in the\n" \
" sources, outputs, and inputs will be all treated as relative to the\n" \
" current build file and converted as needed automatically).\n"
// Common help paragraph on script output directories.
#define SCRIPT_EXECUTION_OUTPUTS \
" All output files must be inside the output directory of the build.\n" \
" You would generally use |$target_out_dir| or |$target_gen_dir| to\n" \
" reference the output or generated intermediate file directories,\n" \
" respectively.\n"
#define ACTION_DEPS \
" The \"deps\" for an action will always be completed before any part\n" \
" of the action is run so it can depend on the output of previous\n" \
" steps. The \"datadeps\" will be built if the action is built, but\n" \
" may not have completed before all steps of the action are started.\n" \
" This can give additional parallelism in the build for runtime-only\n" \
" dependencies.\n"
const char kAction[] = "action";
const char kAction_HelpShort[] =
"action: Declare a target that runs a script a single time.";
const char kAction_Help[] =
"action: Declare a target that runs a script a single time.\n"
"\n"
" This target type allows you to run a script a single time to produce\n"
" or more output files. If you want to run a script once for each of a\n"
" set of input files, see \"gn help action_foreach\".\n"
"\n"
"Inputs\n"
"\n"
" In an action the \"sources\" and \"inputs\" are treated the same:\n"
" they're both input dependencies on script execution with no special\n"
" handling. If you want to pass the sources to your script, you must do\n"
" so explicitly by including them in the \"args\". Note also that this\n"
" means there is no special handling of paths since GN doesn't know\n"
" which of the args are paths and not. You will want to use\n"
" rebase_path() to convert paths to be relative to the root_build_dir.\n"
"\n"
" You can dynamically write input dependencies (for incremental rebuilds\n"
" if an input file changes) by writing a depfile when the script is run\n"
" (see \"gn help depfile\"). This is more flexible than \"inputs\".\n"
"\n"
" It is recommended you put inputs to your script in the \"sources\"\n"
" variable, and stuff like other Python files required to run your\n"
" script in the \"inputs\" variable.\n"
"\n"
ACTION_DEPS
"\n"
"Outputs\n"
"\n"
" You should specify files created by your script by specifying them in\n"
" the \"outputs\".\n"
"\n"
SCRIPT_EXECUTION_CONTEXT
"\n"
"File name handling\n"
"\n"
SCRIPT_EXECUTION_OUTPUTS
"\n"
"Variables\n"
"\n"
" args, data, datadeps, depfile, deps, outputs*, script*,\n"
" inputs, sources\n"
" * = required\n"
"\n"
"Example\n"
"\n"
" action(\"run_this_guy_once\") {\n"
" script = \"doprocessing.py\"\n"
" sources = [ \"my_configuration.txt\" ]\n"
" outputs = [ \"$target_gen_dir/insightful_output.txt\" ]\n"
"\n"
" # Our script imports this Python file so we want to rebuild if it\n"
" # changes.\n"
" inputs = [ \"helper_library.py\" ]\n"
"\n"
" # Note that we have to manually pass the sources to our script if\n"
" # the script needs them as inputs.\n"
" args = [ \"--out\", rebase_path(target_gen_dir, root_build_dir) ] +\n"
" rebase_path(sources, root_build_dir)\n"
" }\n";
Value RunAction(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kAction, scope, function, args,
block, err);
}
// action_foreach --------------------------------------------------------------
const char kActionForEach[] = "action_foreach";
const char kActionForEach_HelpShort[] =
"action_foreach: Declare a target that runs a script over a set of files.";
const char kActionForEach_Help[] =
"action_foreach: Declare a target that runs a script over a set of files.\n"
"\n"
" This target type allows you to run a script once-per-file over a set\n"
" of sources. If you want to run a script once that takes many files as\n"
" input, see \"gn help action\".\n"
"\n"
"Inputs\n"
"\n"
" The script will be run once per file in the \"sources\" variable. The\n"
" \"outputs\" variable should specify one or more files with a source\n"
" expansion pattern in it (see \"gn help source_expansion\"). The output\n"
" file(s) for each script invocation should be unique. Normally you\n"
" use \"{{source_name_part}}\" in each output file.\n"
"\n"
" If your script takes additional data as input, such as a shared\n"
" configuration file or a Python module it uses, those files should be\n"
" listed in the \"inputs\" variable. These files are treated as\n"
" dependencies of each script invocation.\n"
"\n"
" You can dynamically write input dependencies (for incremental rebuilds\n"
" if an input file changes) by writing a depfile when the script is run\n"
" (see \"gn help depfile\"). This is more flexible than \"inputs\".\n"
"\n"
ACTION_DEPS
"\n"
"Outputs\n"
"\n"
SCRIPT_EXECUTION_CONTEXT
"\n"
"File name handling\n"
"\n"
SCRIPT_EXECUTION_OUTPUTS
"\n"
"Variables\n"
"\n"
" args, data, datadeps, depfile, deps, outputs*, script*,\n"
" inputs, sources*\n"
" * = required\n"
"\n"
"Example\n"
"\n"
" # Runs the script over each IDL file. The IDL script will generate\n"
" # both a .cc and a .h file for each input.\n"
" action_foreach(\"my_idl\") {\n"
" script = \"idl_processor.py\"\n"
" sources = [ \"foo.idl\", \"bar.idl\" ]\n"
"\n"
" # Our script reads this file each time, so we need to list is as a\n"
" # dependency so we can rebuild if it changes.\n"
" inputs = [ \"my_configuration.txt\" ]\n"
"\n"
" # Transformation from source file name to output file names.\n"
" outputs = [ \"$target_gen_dir/{{source_name_part}}.h\",\n"
" \"$target_gen_dir/{{source_name_part}}.cc\" ]\n"
"\n"
" # Note that since \"args\" is opaque to GN, if you specify paths\n"
" # here, you will need to convert it to be relative to the build\n"
" # directory using \"rebase_path()\".\n"
" args = [\n"
" \"{{source}}\",\n"
" \"-o\",\n"
" rebase_path(relative_target_gen_dir, root_build_dir) +\n"
" \"/{{source_name_part}}.h\" ]\n"
" }\n"
"\n";
Value RunActionForEach(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kActionForEach, scope, function, args,
block, err);
}
// component -------------------------------------------------------------------
const char kComponent[] = "component";
const char kComponent_HelpShort[] =
"component: Declare a component target.";
const char kComponent_Help[] =
"component: Declare a component target.\n"
"\n"
" A component is a shared library, static library, or source set\n"
" depending on the component mode. This allows a project to separate\n"
" out a build into shared libraries for faster development (link time is\n"
" reduced) but to switch to a static build for releases (for better\n"
" performance).\n"
"\n"
" To use this function you must set the value of the \"component_mode\"\n"
" variable to one of the following strings:\n"
" - \"shared_library\"\n"
" - \"static_library\"\n"
" - \"source_set\"\n"
" It is an error to call \"component\" without defining the mode\n"
" (typically this is done in the master build configuration file).\n";
Value RunComponent(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
// A component is either a shared or static library, depending on the value
// of |component_mode|.
const Value* component_mode_value =
scope->GetValue(variables::kComponentMode);
static const char helptext[] =
"You're declaring a component here but have not defined "
"\"component_mode\" to\neither \"shared_library\" or \"static_library\".";
if (!component_mode_value) {
*err = Err(function->function(), "No component mode set.", helptext);
return Value();
}
if (component_mode_value->type() != Value::STRING ||
(component_mode_value->string_value() != functions::kSharedLibrary &&
component_mode_value->string_value() != functions::kStaticLibrary &&
component_mode_value->string_value() != functions::kSourceSet)) {
*err = Err(function->function(), "Invalid component mode set.", helptext);
return Value();
}
const std::string& component_mode = component_mode_value->string_value();
if (!EnsureNotProcessingImport(function, scope, err))
return Value();
Scope block_scope(scope);
if (!FillTargetBlockScope(scope, function, component_mode.c_str(), block,
args, &block_scope, err))
return Value();
block->ExecuteBlockInScope(&block_scope, err);
if (err->has_error())
return Value();
TargetGenerator::GenerateTarget(&block_scope, function, args,
component_mode, err);
return Value();
}
// copy ------------------------------------------------------------------------
const char kCopy[] = "copy";
const char kCopy_HelpShort[] =
"copy: Declare a target that copies files.";
const char kCopy_Help[] =
"copy: Declare a target that copies files.\n"
"\n"
"File name handling\n"
"\n"
" All output files must be inside the output directory of the build.\n"
" You would generally use |$target_out_dir| or |$target_gen_dir| to\n"
" reference the output or generated intermediate file directories,\n"
" respectively.\n"
"\n"
" Both \"sources\" and \"outputs\" must be specified. Sources can\n"
" as many files as you want, but there can only be one item in the\n"
" outputs list (plural is used for the name for consistency with\n"
" other target types).\n"
"\n"
" If there is more than one source file, your output name should specify\n"
" a mapping from each source files to output file names using source\n"
" expansion (see \"gn help source_expansion\"). The placeholders will\n"
" will look like \"{{source_name_part}}\", for example.\n"
"\n"
"Examples\n"
"\n"
" # Write a rule that copies a checked-in DLL to the output directory.\n"
" copy(\"mydll\") {\n"
" sources = [ \"mydll.dll\" ]\n"
" outputs = [ \"$target_out_dir/mydll.dll\" ]\n"
" }\n"
"\n"
" # Write a rule to copy several files to the target generated files\n"
" # directory.\n"
" copy(\"myfiles\") {\n"
" sources = [ \"data1.dat\", \"data2.dat\", \"data3.dat\" ]\n"
"\n"
" # Use source expansion to generate output files with the\n"
" # corresponding file names in the gen dir. This will just copy each\n"
" # file.\n"
" outputs = [ \"$target_gen_dir/{{source_file_part}}\" ]\n"
" }\n";
Value RunCopy(const FunctionCallNode* function,
const std::vector<Value>& args,
Scope* scope,
Err* err) {
if (!EnsureNotProcessingImport(function, scope, err) ||
!EnsureNotProcessingBuildConfig(function, scope, err))
return Value();
TargetGenerator::GenerateTarget(scope, function, args, functions::kCopy, err);
return Value();
}
// executable ------------------------------------------------------------------
const char kExecutable[] = "executable";
const char kExecutable_HelpShort[] =
"executable: Declare an executable target.";
const char kExecutable_Help[] =
"executable: Declare an executable target.\n"
"\n"
"Variables\n"
"\n"
CONFIG_VALUES_VARS_HELP
DEPS_VARS
DEPENDENT_CONFIG_VARS
GENERAL_TARGET_VARS;
Value RunExecutable(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kExecutable, scope, function, args,
block, err);
}
// group -----------------------------------------------------------------------
const char kGroup[] = "group";
const char kGroup_HelpShort[] =
"group: Declare a named group of targets.";
const char kGroup_Help[] =
"group: Declare a named group of targets.\n"
"\n"
" This target type allows you to create meta-targets that just collect a\n"
" set of dependencies into one named target. Groups can additionally\n"
" specify configs that apply to their dependents.\n"
"\n"
" Depending on a group is exactly like depending directly on that\n"
" group's deps. Direct dependent configs will get automatically\n"
" forwarded through the group so you shouldn't need to use\n"
" \"forward_dependent_configs_from.\n"
"\n"
"Variables\n"
"\n"
DEPS_VARS
DEPENDENT_CONFIG_VARS
"\n"
"Example\n"
"\n"
" group(\"all\") {\n"
" deps = [\n"
" \"//project:runner\",\n"
" \"//project:unit_tests\",\n"
" ]\n"
" }\n";
Value RunGroup(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kGroup, scope, function, args,
block, err);
}
// shared_library --------------------------------------------------------------
const char kSharedLibrary[] = "shared_library";
const char kSharedLibrary_HelpShort[] =
"shared_library: Declare a shared library target.";
const char kSharedLibrary_Help[] =
"shared_library: Declare a shared library target.\n"
"\n"
" A shared library will be specified on the linker line for targets\n"
" listing the shared library in its \"deps\". If you don't want this\n"
" (say you dynamically load the library at runtime), then you should\n"
" depend on the shared library via \"datadeps\" instead.\n"
"\n"
"Variables\n"
"\n"
CONFIG_VALUES_VARS_HELP
DEPS_VARS
DEPENDENT_CONFIG_VARS
GENERAL_TARGET_VARS;
Value RunSharedLibrary(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kSharedLibrary, scope, function, args,
block, err);
}
// source_set ------------------------------------------------------------------
extern const char kSourceSet[] = "source_set";
extern const char kSourceSet_HelpShort[] =
"source_set: Declare a source set target.";
extern const char kSourceSet_Help[] =
"source_set: Declare a source set target.\n"
"\n"
" A source set is a collection of sources that get compiled, but are not\n"
" linked to produce any kind of library. Instead, the resulting object\n"
" files are implicitly added to the linker line of all targets that\n"
" depend on the source set.\n"
"\n"
" In most cases, a source set will behave like a static library, except\n"
" no actual library file will be produced. This will make the build go\n"
" a little faster by skipping creation of a large static library, while\n"
" maintaining the organizational benefits of focused build targets.\n"
"\n"
" The main difference between a source set and a static library is\n"
" around handling of exported symbols. Most linkers assume declaring\n"
" a function exported means exported from the static library. The linker\n"
" can then do dead code elimination to delete code not reachable from\n"
" exported functions.\n"
"\n"
" A source set will not do this code elimination since there is no link\n"
" step. This allows you to link many sources sets into a shared library\n"
" and have the \"exported symbol\" notation indicate \"export from the\n"
" final shared library and not from the intermediate targets.\" There is\n"
" no way to express this concept when linking multiple static libraries\n"
" into a shared library.\n"
"\n"
"Variables\n"
"\n"
CONFIG_VALUES_VARS_HELP
DEPS_VARS
DEPENDENT_CONFIG_VARS
GENERAL_TARGET_VARS;
Value RunSourceSet(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kSourceSet, scope, function, args,
block, err);
}
// static_library --------------------------------------------------------------
const char kStaticLibrary[] = "static_library";
const char kStaticLibrary_HelpShort[] =
"static_library: Declare a static library target.";
const char kStaticLibrary_Help[] =
"static_library: Declare a static library target.\n"
"\n"
" Make a \".a\" / \".lib\" file.\n"
"\n"
" If you only need the static library for intermediate results in the\n"
" build, you should consider a source_set instead since it will skip\n"
" the (potentially slow) step of creating the intermediate library file.\n"
"\n"
"Variables\n"
"\n"
CONFIG_VALUES_VARS_HELP
DEPS_VARS
DEPENDENT_CONFIG_VARS
GENERAL_TARGET_VARS;
Value RunStaticLibrary(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kStaticLibrary, scope, function, args,
block, err);
}
// test ------------------------------------------------------------------------
const char kTest[] = "test";
const char kTest_HelpShort[] =
"test: Declares a test target.";
const char kTest_Help[] =
"test: Declares a test target.\n"
"\n"
" This is like an executable target, but is named differently to make\n"
" the purpose of the target more obvious. It's possible in the future\n"
" we can do some enhancements like \"list all of the tests in a given\n"
" directory\".\n"
"\n"
" See \"gn help executable\" for usage.\n";
Value RunTest(Scope* scope,
const FunctionCallNode* function,
const std::vector<Value>& args,
BlockNode* block,
Err* err) {
return ExecuteGenericTarget(functions::kExecutable, scope, function, args,
block, err);
}
} // namespace functions