src/tools/gn/functions_target.cc

   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.
   4
   5 #include "tools/gn/functions.h"
   6
   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"
  14
  15 #define DEPENDENT_CONFIG_VARS \
  16     "  Dependent configs: all_dependent_configs, direct_dependent_configs\n"
  17 #define DEPS_VARS \
  18     "  Deps: data, datadeps, deps, forward_dependent_configs_from, hard_dep\n"
  19 #define GENERAL_TARGET_VARS \
  20     "  General: configs, source_prereqs, sources\n"
  21
  22 namespace functions {
  23
  24 namespace {
  25
  26 Value ExecuteGenericTarget(const char* target_type,
  27                            Scope* scope,
  28                            const FunctionCallNode* function,
  29                            const std::vector<Value>& args,
  30                            BlockNode* block,
  31                            Err* err) {
  32   if (!EnsureNotProcessingImport(function, scope, err) ||
  33       !EnsureNotProcessingBuildConfig(function, scope, err))
  34     return Value();
  35   Scope block_scope(scope);
  36   if (!FillTargetBlockScope(scope, function, target_type, block,
  37                             args, &block_scope, err))
  38     return Value();
  39
  40   block->ExecuteBlockInScope(&block_scope, err);
  41   if (err->has_error())
  42     return Value();
  43
  44   TargetGenerator::GenerateTarget(&block_scope, function, args,
  45                                   target_type, err);
  46   if (err->has_error())
  47     return Value();
  48
  49   block_scope.CheckForUnusedVars(err);
  50   return Value();
  51 }
  52
  53 }  // namespace
  54
  55 // action ----------------------------------------------------------------------
  56
  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"
  65
  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" \
  71     "  respectively.\n"
  72
  73 #define ACTION_DEPS \
  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" \
  79     "  dependencies.\n"
  80
  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"
  86     "\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"
  90     "\n"
  91     "Inputs\n"
  92     "\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"
 100     "\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"
 104     "\n"
 105     ACTION_DEPS
 106     "\n"
 107     "Outputs\n"
 108     "\n"
 109     "  You should specify files created by your script by specifying them in\n"
 110     "  the \"outputs\".\n"
 111     "\n"
 112     SCRIPT_EXECUTION_CONTEXT
 113     "\n"
 114     "File name handling\n"
 115     "\n"
 116     SCRIPT_EXECUTION_OUTPUTS
 117     "\n"
 118     "Variables\n"
 119     "\n"
 120     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
 121     "  source_prereqs, sources\n"
 122     "  * = required\n"
 123     "\n"
 124     "Example\n"
 125     "\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"
 130     "\n"
 131     "    # Our script imports this Python file so we want to rebuild if it\n"
 132     "    # changes.\n"
 133     "    source_prereqs = [ \"helper_library.py\" ]\n"
 134     "\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"
 139     "  }\n";
 140
 141 Value RunAction(Scope* scope,
 142                 const FunctionCallNode* function,
 143                 const std::vector<Value>& args,
 144                 BlockNode* block,
 145                 Err* err) {
 146   return ExecuteGenericTarget(functions::kAction, scope, function, args,
 147                               block, err);
 148 }
 149
 150 // action_foreach --------------------------------------------------------------
 151
 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"
 157     "\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"
 161     "\n"
 162     "Inputs\n"
 163     "\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"
 169     "\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"
 174     "\n"
 175     ACTION_DEPS
 176     "\n"
 177     "Outputs\n"
 178     "\n"
 179     SCRIPT_EXECUTION_CONTEXT
 180     "\n"
 181     "File name handling\n"
 182     "\n"
 183     SCRIPT_EXECUTION_OUTPUTS
 184     "\n"
 185     "Variables\n"
 186     "\n"
 187     "  args, data, datadeps, depfile, deps, outputs*, script*,\n"
 188     "  source_prereqs, sources*\n"
 189     "  * = required\n"
 190     "\n"
 191     "Example\n"
 192     "\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"
 198     "\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"
 202     "\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"
 206     "\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"
 210     "    args = [\n"
 211     "      \"{{source}}\",\n"
 212     "      \"-o\",\n"
 213     "      rebase_path(relative_target_gen_dir, root_build_dir) +\n"
 214     "        \"/{{source_name_part}}.h\" ]\n"
 215     "  }\n"
 216     "\n";
 217 Value RunActionForEach(Scope* scope,
 218                        const FunctionCallNode* function,
 219                        const std::vector<Value>& args,
 220                        BlockNode* block,
 221                        Err* err) {
 222   return ExecuteGenericTarget(functions::kActionForEach, scope, function, args,
 223                               block, err);
 224 }
 225
 226 // component -------------------------------------------------------------------
 227
 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"
 233     "\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"
 238     "  performance).\n"
 239     "\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";
 247
 248 Value RunComponent(Scope* scope,
 249                    const FunctionCallNode* function,
 250                    const std::vector<Value>& args,
 251                    BlockNode* block,
 252                    Err* err) {
 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);
 257
 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);
 263     return Value();
 264   }
 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);
 270     return Value();
 271   }
 272   const std::string& component_mode = component_mode_value->string_value();
 273
 274   if (!EnsureNotProcessingImport(function, scope, err))
 275     return Value();
 276   Scope block_scope(scope);
 277   if (!FillTargetBlockScope(scope, function, component_mode.c_str(), block,
 278                             args, &block_scope, err))
 279     return Value();
 280
 281   block->ExecuteBlockInScope(&block_scope, err);
 282   if (err->has_error())
 283     return Value();
 284
 285   TargetGenerator::GenerateTarget(&block_scope, function, args,
 286                                   component_mode, err);
 287   return Value();
 288 }
 289
 290 // copy ------------------------------------------------------------------------
 291
 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"
 297     "\n"
 298     "File name handling\n"
 299     "\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"
 303     "  respectively.\n"
 304     "\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"
 309     "\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"
 314     "\n"
 315     "Examples\n"
 316     "\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"
 321     "  }\n"
 322     "\n"
 323     "  # Write a rule to copy several files to the target generated files\n"
 324     "  # directory.\n"
 325     "  copy(\"myfiles\") {\n"
 326     "    sources = [ \"data1.dat\", \"data2.dat\", \"data3.dat\" ]\n"
 327     "\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"
 330     "    # file.\n"
 331     "    outputs = [ \"$target_gen_dir/{{source_file_part}}\" ]\n"
 332     "  }\n";
 333
 334 Value RunCopy(const FunctionCallNode* function,
 335               const std::vector<Value>& args,
 336               Scope* scope,
 337               Err* err) {
 338   if (!EnsureNotProcessingImport(function, scope, err) ||
 339       !EnsureNotProcessingBuildConfig(function, scope, err))
 340     return Value();
 341   TargetGenerator::GenerateTarget(scope, function, args, functions::kCopy, err);
 342   return Value();
 343 }
 344
 345 // executable ------------------------------------------------------------------
 346
 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"
 352     "\n"
 353     "Variables\n"
 354     "\n"
 355     CONFIG_VALUES_VARS_HELP
 356     DEPS_VARS
 357     DEPENDENT_CONFIG_VARS
 358     GENERAL_TARGET_VARS;
 359
 360 Value RunExecutable(Scope* scope,
 361                     const FunctionCallNode* function,
 362                     const std::vector<Value>& args,
 363                     BlockNode* block,
 364                     Err* err) {
 365   return ExecuteGenericTarget(functions::kExecutable, scope, function, args,
 366                               block, err);
 367 }
 368
 369 // group -----------------------------------------------------------------------
 370
 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"
 376     "\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"
 380     "\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"
 385     "\n"
 386     "Variables\n"
 387     "\n"
 388     DEPS_VARS
 389     DEPENDENT_CONFIG_VARS
 390     "\n"
 391     "Example\n"
 392     "\n"
 393     "  group(\"all\") {\n"
 394     "    deps = [\n"
 395     "      \"//project:runner\",\n"
 396     "      \"//project:unit_tests\",\n"
 397     "    ]\n"
 398     "  }\n";
 399
 400 Value RunGroup(Scope* scope,
 401                const FunctionCallNode* function,
 402                const std::vector<Value>& args,
 403                BlockNode* block,
 404                Err* err) {
 405   return ExecuteGenericTarget(functions::kGroup, scope, function, args,
 406                               block, err);
 407 }
 408
 409 // shared_library --------------------------------------------------------------
 410
 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"
 416     "\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"
 421     "\n"
 422     "Variables\n"
 423     "\n"
 424     CONFIG_VALUES_VARS_HELP
 425     DEPS_VARS
 426     DEPENDENT_CONFIG_VARS
 427     GENERAL_TARGET_VARS;
 428
 429 Value RunSharedLibrary(Scope* scope,
 430                        const FunctionCallNode* function,
 431                        const std::vector<Value>& args,
 432                        BlockNode* block,
 433                        Err* err) {
 434   return ExecuteGenericTarget(functions::kSharedLibrary, scope, function, args,
 435                               block, err);
 436 }
 437
 438 // source_set ------------------------------------------------------------------
 439
 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"
 445     "\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"
 450     "\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"
 455     "\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"
 461     "\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"
 468     "\n"
 469     "Variables\n"
 470     "\n"
 471     CONFIG_VALUES_VARS_HELP
 472     DEPS_VARS
 473     DEPENDENT_CONFIG_VARS
 474     GENERAL_TARGET_VARS;
 475
 476 Value RunSourceSet(Scope* scope,
 477                    const FunctionCallNode* function,
 478                    const std::vector<Value>& args,
 479                    BlockNode* block,
 480                    Err* err) {
 481   return ExecuteGenericTarget(functions::kSourceSet, scope, function, args,
 482                               block, err);
 483 }
 484
 485 // static_library --------------------------------------------------------------
 486
 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"
 492     "\n"
 493     "  Make a \".a\" / \".lib\" file.\n"
 494     "\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"
 498     "\n"
 499     "Variables\n"
 500     "\n"
 501     CONFIG_VALUES_VARS_HELP
 502     DEPS_VARS
 503     DEPENDENT_CONFIG_VARS
 504     GENERAL_TARGET_VARS;
 505
 506 Value RunStaticLibrary(Scope* scope,
 507                        const FunctionCallNode* function,
 508                        const std::vector<Value>& args,
 509                        BlockNode* block,
 510                        Err* err) {
 511   return ExecuteGenericTarget(functions::kStaticLibrary, scope, function, args,
 512                               block, err);
 513 }
 514
 515 // test ------------------------------------------------------------------------
 516
 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"
 522     "\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"
 526     "  directory\".\n"
 527     "\n"
 528     "  See \"gn help executable\" for usage.\n";
 529
 530 Value RunTest(Scope* scope,
 531               const FunctionCallNode* function,
 532               const std::vector<Value>& args,
 533               BlockNode* block,
 534               Err* err) {
 535   return ExecuteGenericTarget(functions::kExecutable, scope, function, args,
 536                               block, err);
 537 }
 538
 539 }  // namespace functions