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, external, 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 // component ------------------------------------------------------------------- 56 57 const char kComponent[] = "component"; 58 const char kComponent_Help[] = 59 "component: Declare a component target.\n" 60 "\n" 61 " A component is a shared library, static library, or source set\n" 62 " depending on the component mode. This allows a project to separate\n" 63 " out a build into shared libraries for faster devlopment (link time is\n" 64 " reduced) but to switch to a static build for releases (for better\n" 65 " performance).\n" 66 "\n" 67 " To use this function you must set the value of the \"component_mode\n" 68 " variable to one of the following strings:\n" 69 " - \"shared_library\"\n" 70 " - \"static_library\"\n" 71 " - \"source_set\"\n" 72 " It is an error to call \"component\" without defining the mode\n" 73 " (typically this is done in the master build configuration file).\n"; 74 75 Value RunComponent(Scope* scope, 76 const FunctionCallNode* function, 77 const std::vector<Value>& args, 78 BlockNode* block, 79 Err* err) { 80 // A component is either a shared or static library, depending on the value 81 // of |component_mode|. 82 const Value* component_mode_value = 83 scope->GetValue(variables::kComponentMode); 84 85 static const char helptext[] = 86 "You're declaring a component here but have not defined " 87 "\"component_mode\" to\neither \"shared_library\" or \"static_library\"."; 88 if (!component_mode_value) { 89 *err = Err(function->function(), "No component mode set.", helptext); 90 return Value(); 91 } 92 if (component_mode_value->type() != Value::STRING || 93 (component_mode_value->string_value() != functions::kSharedLibrary && 94 component_mode_value->string_value() != functions::kStaticLibrary && 95 component_mode_value->string_value() != functions::kSourceSet)) { 96 *err = Err(function->function(), "Invalid component mode set.", helptext); 97 return Value(); 98 } 99 const std::string& component_mode = component_mode_value->string_value(); 100 101 if (!EnsureNotProcessingImport(function, scope, err)) 102 return Value(); 103 Scope block_scope(scope); 104 if (!FillTargetBlockScope(scope, function, component_mode.c_str(), block, 105 args, &block_scope, err)) 106 return Value(); 107 108 block->ExecuteBlockInScope(&block_scope, err); 109 if (err->has_error()) 110 return Value(); 111 112 TargetGenerator::GenerateTarget(&block_scope, function, args, 113 component_mode, err); 114 return Value(); 115 } 116 117 // copy ------------------------------------------------------------------------ 118 119 const char kCopy[] = "copy"; 120 const char kCopy_Help[] = 121 "copy: Declare a target that copies files.\n" 122 "\n" 123 "File name handling\n" 124 "\n" 125 " All output files must be inside the output directory of the build.\n" 126 " You would generally use |$target_out_dir| or |$target_gen_dir| to\n" 127 " reference the output or generated intermediate file directories,\n" 128 " respectively.\n" 129 "\n" 130 " Both \"sources\" and \"outputs\" must be specified. Sources can\n" 131 " as many files as you want, but there can only be one item in the\n" 132 " outputs list (plural is used for the name for consistency with\n" 133 " other target types).\n" 134 "\n" 135 " If there is more than one source file, your output name should specify\n" 136 " a mapping from each source files to output file names using source\n" 137 " expansion (see \"gn help source_expansion\"). The placeholders will\n" 138 " will look like \"{{source_name_part}}\", for example.\n" 139 "\n" 140 "Examples\n" 141 "\n" 142 " # Write a rule that copies a checked-in DLL to the output directory.\n" 143 " copy(\"mydll\") {\n" 144 " sources = [ \"mydll.dll\" ]\n" 145 " outputs = [ \"$target_out_dir/mydll.dll\" ]\n" 146 " }\n" 147 "\n" 148 " # Write a rule to copy several files to the target generated files\n" 149 " # directory.\n" 150 " copy(\"myfiles\") {\n" 151 " sources = [ \"data1.dat\", \"data2.dat\", \"data3.dat\" ]\n" 152 "\n" 153 " # Use source expansion to generate output files with the\n" 154 " # corresponding file names in the gen dir. This will just copy each\n" 155 " # file.\n" 156 " outputs = [ \"$target_gen_dir/{{source_file_part}}\" ]\n" 157 " }\n"; 158 159 Value RunCopy(const FunctionCallNode* function, 160 const std::vector<Value>& args, 161 Scope* scope, 162 Err* err) { 163 if (!EnsureNotProcessingImport(function, scope, err) || 164 !EnsureNotProcessingBuildConfig(function, scope, err)) 165 return Value(); 166 TargetGenerator::GenerateTarget(scope, function, args, functions::kCopy, err); 167 return Value(); 168 } 169 170 // custom ---------------------------------------------------------------------- 171 172 const char kCustom[] = "custom"; 173 const char kCustom_Help[] = 174 "custom: Declare a script-generated target.\n" 175 "\n" 176 " This target type allows you to run a script over a set of source\n" 177 " files and generate a set of output files.\n" 178 "\n" 179 " The script will be executed with the given arguments with the current\n" 180 " directory being that of the root build directory. If you pass files\n" 181 " to your script, see \"gn help to_build_path\" for how to convert\n" 182 " file names to be relative to the build directory (file names in the\n" 183 " sources, outputs, and source_prereqs will be all treated as relative\n" 184 " to the current build file and converted as needed automatically).\n" 185 "\n" 186 " There are two modes. The first mode is the \"per-file\" mode where you\n" 187 " specify a list of sources and the script is run once for each one as a\n" 188 " build rule. In this case, each file specified in the |outputs|\n" 189 " variable must be unique when applied to each source file (normally you\n" 190 " would reference |{{source_name_part}}| from within each one) or the\n" 191 " build system will get confused about how to build those files. You\n" 192 " should use the |source_prereqs| variable to list all additional\n" 193 " dependencies of your script: these will be added as dependencies for\n" 194 " each build step.\n" 195 "\n" 196 " The second mode is when you just want to run a script once rather than\n" 197 " as a general rule over a set of files. In this case you don't list any\n" 198 " sources. Dependencies of your script are specified only in the\n" 199 " |source_prereqs| variable and your |outputs| variable should just list\n" 200 " all outputs.\n" 201 "\n" 202 "File name handling\n" 203 "\n" 204 " All output files must be inside the output directory of the build.\n" 205 " You would generally use |$target_out_dir| or |$target_gen_dir| to\n" 206 " reference the output or generated intermediate file directories,\n" 207 " respectively.\n" 208 "\n" 209 " You can specify a mapping from source files to output files using\n" 210 " source expansion (see \"gn help source_expansion\"). The placeholders\n" 211 " will look like \"{{source}}\", for example, and can appear in\n" 212 " either the outputs or the args lists.\n" 213 "\n" 214 "Variables\n" 215 "\n" 216 " args, deps, outputs, script*, source_prereqs, sources\n" 217 " * = required\n" 218 "\n" 219 "Examples\n" 220 "\n" 221 " # Runs the script over each IDL file. The IDL script will generate\n" 222 " # both a .cc and a .h file for each input.\n" 223 " custom(\"general_rule\") {\n" 224 " script = \"idl_processor.py\"\n" 225 " sources = [ \"foo.idl\", \"bar.idl\" ]\n" 226 " source_prereqs = [ \"my_configuration.txt\" ]\n" 227 " outputs = [ \"$target_gen_dir/{{source_name_part}}.h\",\n" 228 " \"$target_gen_dir/{{source_name_part}}.cc\" ]\n" 229 "\n" 230 " # Note that since \"args\" is opaque to GN, if you specify paths\n" 231 " # here, you will need to convert it to be relative to the build\n" 232 " # directory using \"to_build_path()\".\n" 233 " args = [ \"{{source}}\",\n" 234 " \"-o\",\n" 235 " to_build_path(relative_target_gen_dir) + \"/\" +\n" 236 " {{source_name_part}}.h\" ]\n" 237 " }\n" 238 "\n" 239 " custom(\"just_run_this_guy_once\") {\n" 240 " script = \"doprocessing.py\"\n" 241 " source_prereqs = [ \"my_configuration.txt\" ]\n" 242 " outputs = [ \"$target_gen_dir/insightful_output.txt\" ]\n" 243 " args = [ \"--output_dir\", to_build_path(target_gen_dir) ]\n" 244 " }\n"; 245 246 Value RunCustom(Scope* scope, 247 const FunctionCallNode* function, 248 const std::vector<Value>& args, 249 BlockNode* block, 250 Err* err) { 251 return ExecuteGenericTarget(functions::kCustom, scope, function, args, 252 block, err); 253 } 254 255 // executable ------------------------------------------------------------------ 256 257 const char kExecutable[] = "executable"; 258 const char kExecutable_Help[] = 259 "executable: Declare an executable target.\n" 260 "\n" 261 "Variables\n" 262 "\n" 263 CONFIG_VALUES_VARS_HELP 264 DEPS_VARS 265 DEPENDENT_CONFIG_VARS 266 GENERAL_TARGET_VARS; 267 268 Value RunExecutable(Scope* scope, 269 const FunctionCallNode* function, 270 const std::vector<Value>& args, 271 BlockNode* block, 272 Err* err) { 273 return ExecuteGenericTarget(functions::kExecutable, scope, function, args, 274 block, err); 275 } 276 277 // group ----------------------------------------------------------------------- 278 279 const char kGroup[] = "group"; 280 const char kGroup_Help[] = 281 "group: Declare a named group of targets.\n" 282 "\n" 283 " This target type allows you to create meta-targets that just collect a\n" 284 " set of dependencies into one named target. Groups can additionally\n" 285 " specify configs that apply to their dependents.\n" 286 "\n" 287 " Depending on a group is exactly like depending directly on that\n" 288 " group's deps. Direct dependent configs will get automatically fowarded\n" 289 " through the group so you shouldn't need to use\n" 290 " \"forward_dependent_configs_from.\n" 291 "\n" 292 "Variables\n" 293 "\n" 294 DEPS_VARS 295 DEPENDENT_CONFIG_VARS 296 " Other variables: external\n" 297 "\n" 298 "Example\n" 299 "\n" 300 " group(\"all\") {\n" 301 " deps = [\n" 302 " \"//project:runner\",\n" 303 " \"//project:unit_tests\",\n" 304 " ]\n" 305 " }\n"; 306 307 Value RunGroup(Scope* scope, 308 const FunctionCallNode* function, 309 const std::vector<Value>& args, 310 BlockNode* block, 311 Err* err) { 312 return ExecuteGenericTarget(functions::kGroup, scope, function, args, 313 block, err); 314 } 315 316 // shared_library -------------------------------------------------------------- 317 318 const char kSharedLibrary[] = "shared_library"; 319 const char kSharedLibrary_Help[] = 320 "shared_library: Declare a shared library target.\n" 321 "\n" 322 " A shared library will be specified on the linker line for targets\n" 323 " listing the shared library in its \"deps\". If you don't want this\n" 324 " (say you dynamically load the library at runtime), then you should\n" 325 " depend on the shared library via \"datadeps\" instead.\n" 326 "\n" 327 "Variables\n" 328 "\n" 329 CONFIG_VALUES_VARS_HELP 330 DEPS_VARS 331 DEPENDENT_CONFIG_VARS 332 GENERAL_TARGET_VARS; 333 334 Value RunSharedLibrary(Scope* scope, 335 const FunctionCallNode* function, 336 const std::vector<Value>& args, 337 BlockNode* block, 338 Err* err) { 339 return ExecuteGenericTarget(functions::kSharedLibrary, scope, function, args, 340 block, err); 341 } 342 343 // source_set ------------------------------------------------------------------ 344 345 extern const char kSourceSet[] = "source_set"; 346 extern const char kSourceSet_Help[] = 347 "source_set: Declare a source set target.\n" 348 "\n" 349 " A source set is a collection of sources that get compiled, but are not\n" 350 " linked to produce any kind of library. Instead, the resulting object\n" 351 " files are implicitly added to the linker line of all targets that\n" 352 " depend on the source set.\n" 353 "\n" 354 " In most cases, a source set will behave like a static library, except\n" 355 " no actual library file will be produced. This will make the build go\n" 356 " a little faster by skipping creation of a large static library, while\n" 357 " maintaining the organizational benefits of focused build targets.\n" 358 "\n" 359 " The main difference between a source set and a static library is\n" 360 " around handling of exported symbols. Most linkers assume declaring\n" 361 " a function exported means exported from the static library. The linker\n" 362 " can then do dead code elimination to delete code not reachable from\n" 363 " exported functions.\n" 364 "\n" 365 " A source set will not do this code elimination since there is no link\n" 366 " step. This allows you to link many sources sets into a shared library\n" 367 " and have the \"exported symbol\" notation indicate \"export from the\n" 368 " final shared library and not from the intermediate targets.\" There is\n" 369 " no way to express this concept when linking multiple static libraries\n" 370 " into a shared library.\n" 371 "\n" 372 "Variables\n" 373 "\n" 374 CONFIG_VALUES_VARS_HELP 375 DEPS_VARS 376 DEPENDENT_CONFIG_VARS 377 GENERAL_TARGET_VARS; 378 379 Value RunSourceSet(Scope* scope, 380 const FunctionCallNode* function, 381 const std::vector<Value>& args, 382 BlockNode* block, 383 Err* err) { 384 return ExecuteGenericTarget(functions::kSourceSet, scope, function, args, 385 block, err); 386 } 387 388 // static_library -------------------------------------------------------------- 389 390 const char kStaticLibrary[] = "static_library"; 391 const char kStaticLibrary_Help[] = 392 "static_library: Declare a static library target.\n" 393 "\n" 394 " Make a \".a\" / \".lib\" file.\n" 395 "\n" 396 " If you only need the static library for intermediate results in the\n" 397 " build, you should consider a source_set instead since it will skip\n" 398 " the (potentially slow) step of creating the intermediate library file.\n" 399 "\n" 400 "Variables\n" 401 "\n" 402 CONFIG_VALUES_VARS_HELP 403 DEPS_VARS 404 DEPENDENT_CONFIG_VARS 405 GENERAL_TARGET_VARS; 406 407 Value RunStaticLibrary(Scope* scope, 408 const FunctionCallNode* function, 409 const std::vector<Value>& args, 410 BlockNode* block, 411 Err* err) { 412 return ExecuteGenericTarget(functions::kStaticLibrary, scope, function, args, 413 block, err); 414 } 415 416 // test ------------------------------------------------------------------------ 417 418 const char kTest[] = "test"; 419 const char kTest_Help[] = 420 "test: Declares a test target.\n" 421 "\n" 422 " This is like an executable target, but is named differently to make\n" 423 " the purpose of the target more obvious. It's possible in the future\n" 424 " we can do some enhancements like \"list all of the tests in a given\n" 425 " directory\".\n" 426 "\n" 427 " See \"gn help executable\" for usage.\n"; 428 429 Value RunTest(Scope* scope, 430 const FunctionCallNode* function, 431 const std::vector<Value>& args, 432 BlockNode* block, 433 Err* err) { 434 return ExecuteGenericTarget(functions::kExecutable, scope, function, args, 435 block, err); 436 } 437 438 } // namespace functions 439
