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 #ifndef TOOLS_GN_FUNCTIONS_H_ 6 #define TOOLS_GN_FUNCTIONS_H_ 7 8 #include <map> 9 #include <string> 10 #include <string_view> 11 #include <vector> 12 13 class Err; 14 class BlockNode; 15 class FunctionCallNode; 16 class Label; 17 class ListNode; 18 class ParseNode; 19 class Scope; 20 class Value; 21 22 // ----------------------------------------------------------------------------- 23 24 namespace functions { 25 26 // This type of function invocation has no block and evaluates its arguments 27 // itself rather than taking a pre-executed list. This allows us to implement 28 // certain built-in functions. 29 using SelfEvaluatingArgsFunction = Value (*)(Scope* scope, 30 const FunctionCallNode* function, 31 const ListNode* args_list, 32 Err* err); 33 34 // This type of function invocation takes a block node that it will execute. 35 using GenericBlockFunction = Value (*)(Scope* scope, 36 const FunctionCallNode* function, 37 const std::vector<Value>& args, 38 BlockNode* block, 39 Err* err); 40 41 // This type of function takes a block, but does not need to control execution 42 // of it. The dispatch function will pre-execute the block and pass the 43 // resulting block_scope to the function. 44 using ExecutedBlockFunction = Value (*)(const FunctionCallNode* function, 45 const std::vector<Value>& args, 46 Scope* block_scope, 47 Err* err); 48 49 // This type of function does not take a block. It just has arguments. 50 using NoBlockFunction = Value (*)(Scope* scope, 51 const FunctionCallNode* function, 52 const std::vector<Value>& args, 53 Err* err); 54 55 extern const char kAction[]; 56 extern const char kAction_HelpShort[]; 57 extern const char kAction_Help[]; 58 Value RunAction(Scope* scope, 59 const FunctionCallNode* function, 60 const std::vector<Value>& args, 61 BlockNode* block, 62 Err* err); 63 64 extern const char kActionForEach[]; 65 extern const char kActionForEach_HelpShort[]; 66 extern const char kActionForEach_Help[]; 67 Value RunActionForEach(Scope* scope, 68 const FunctionCallNode* function, 69 const std::vector<Value>& args, 70 BlockNode* block, 71 Err* err); 72 73 extern const char kAssert[]; 74 extern const char kAssert_HelpShort[]; 75 extern const char kAssert_Help[]; 76 Value RunAssert(Scope* scope, 77 const FunctionCallNode* function, 78 const std::vector<Value>& args, 79 Err* err); 80 81 extern const char kBundleData[]; 82 extern const char kBundleData_HelpShort[]; 83 extern const char kBundleData_Help[]; 84 Value RunBundleData(Scope* scope, 85 const FunctionCallNode* function, 86 const std::vector<Value>& args, 87 BlockNode* block, 88 Err* err); 89 90 extern const char kCreateBundle[]; 91 extern const char kCreateBundle_HelpShort[]; 92 extern const char kCreateBundle_Help[]; 93 Value RunCreateBundle(Scope* scope, 94 const FunctionCallNode* function, 95 const std::vector<Value>& args, 96 BlockNode* block, 97 Err* err); 98 99 extern const char kConfig[]; 100 extern const char kConfig_HelpShort[]; 101 extern const char kConfig_Help[]; 102 Value RunConfig(const FunctionCallNode* function, 103 const std::vector<Value>& args, 104 Scope* block_scope, 105 Err* err); 106 107 extern const char kCopy[]; 108 extern const char kCopy_HelpShort[]; 109 extern const char kCopy_Help[]; 110 Value RunCopy(const FunctionCallNode* function, 111 const std::vector<Value>& args, 112 Scope* block_scope, 113 Err* err); 114 115 extern const char kDeclareArgs[]; 116 extern const char kDeclareArgs_HelpShort[]; 117 extern const char kDeclareArgs_Help[]; 118 Value RunDeclareArgs(Scope* scope, 119 const FunctionCallNode* function, 120 const std::vector<Value>& args, 121 BlockNode* block, 122 Err* err); 123 124 extern const char kDefined[]; 125 extern const char kDefined_HelpShort[]; 126 extern const char kDefined_Help[]; 127 Value RunDefined(Scope* scope, 128 const FunctionCallNode* function, 129 const ListNode* args_list, 130 Err* err); 131 132 extern const char kExecScript[]; 133 extern const char kExecScript_HelpShort[]; 134 extern const char kExecScript_Help[]; 135 Value RunExecScript(Scope* scope, 136 const FunctionCallNode* function, 137 const std::vector<Value>& args, 138 Err* err); 139 140 extern const char kExecutable[]; 141 extern const char kExecutable_HelpShort[]; 142 extern const char kExecutable_Help[]; 143 Value RunExecutable(Scope* scope, 144 const FunctionCallNode* function, 145 const std::vector<Value>& args, 146 BlockNode* block, 147 Err* err); 148 149 extern const char kFilterExclude[]; 150 extern const char kFilterExclude_HelpShort[]; 151 extern const char kFilterExclude_Help[]; 152 Value RunFilterExclude(Scope* scope, 153 const FunctionCallNode* function, 154 const std::vector<Value>& args, 155 Err* err); 156 157 extern const char kFilterInclude[]; 158 extern const char kFilterInclude_HelpShort[]; 159 extern const char kFilterInclude_Help[]; 160 Value RunFilterInclude(Scope* scope, 161 const FunctionCallNode* function, 162 const std::vector<Value>& args, 163 Err* err); 164 165 extern const char kFilterLabelsInclude[]; 166 extern const char kFilterLabelsInclude_HelpShort[]; 167 extern const char kFilterLabelsInclude_Help[]; 168 Value RunFilterLabelsInclude(Scope* scope, 169 const FunctionCallNode* function, 170 const std::vector<Value>& args, 171 Err* err); 172 173 extern const char kFilterLabelsExclude[]; 174 extern const char kFilterLabelsExclude_HelpShort[]; 175 extern const char kFilterLabelsExclude_Help[]; 176 Value RunFilterLabelsExclude(Scope* scope, 177 const FunctionCallNode* function, 178 const std::vector<Value>& args, 179 Err* err); 180 181 extern const char kForEach[]; 182 extern const char kForEach_HelpShort[]; 183 extern const char kForEach_Help[]; 184 Value RunForEach(Scope* scope, 185 const FunctionCallNode* function, 186 const ListNode* args_list, 187 Err* err); 188 189 extern const char kForwardVariablesFrom[]; 190 extern const char kForwardVariablesFrom_HelpShort[]; 191 extern const char kForwardVariablesFrom_Help[]; 192 Value RunForwardVariablesFrom(Scope* scope, 193 const FunctionCallNode* function, 194 const ListNode* args_list, 195 Err* err); 196 197 extern const char kGetEnv[]; 198 extern const char kGetEnv_HelpShort[]; 199 extern const char kGetEnv_Help[]; 200 Value RunGetEnv(Scope* scope, 201 const FunctionCallNode* function, 202 const std::vector<Value>& args, 203 Err* err); 204 205 extern const char kGetLabelInfo[]; 206 extern const char kGetLabelInfo_HelpShort[]; 207 extern const char kGetLabelInfo_Help[]; 208 Value RunGetLabelInfo(Scope* scope, 209 const FunctionCallNode* function, 210 const std::vector<Value>& args, 211 Err* err); 212 213 extern const char kGetPathInfo[]; 214 extern const char kGetPathInfo_HelpShort[]; 215 extern const char kGetPathInfo_Help[]; 216 Value RunGetPathInfo(Scope* scope, 217 const FunctionCallNode* function, 218 const std::vector<Value>& args, 219 Err* err); 220 221 extern const char kGetTargetOutputs[]; 222 extern const char kGetTargetOutputs_HelpShort[]; 223 extern const char kGetTargetOutputs_Help[]; 224 Value RunGetTargetOutputs(Scope* scope, 225 const FunctionCallNode* function, 226 const std::vector<Value>& args, 227 Err* err); 228 229 extern const char kGeneratedFile[]; 230 extern const char kGeneratedFile_HelpShort[]; 231 extern const char kGeneratedFile_Help[]; 232 Value RunGeneratedFile(Scope* scope, 233 const FunctionCallNode* function, 234 const std::vector<Value>& args, 235 BlockNode* block, 236 Err* err); 237 238 extern const char kGroup[]; 239 extern const char kGroup_HelpShort[]; 240 extern const char kGroup_Help[]; 241 Value RunGroup(Scope* scope, 242 const FunctionCallNode* function, 243 const std::vector<Value>& args, 244 BlockNode* block, 245 Err* err); 246 247 extern const char kImport[]; 248 extern const char kImport_HelpShort[]; 249 extern const char kImport_Help[]; 250 Value RunImport(Scope* scope, 251 const FunctionCallNode* function, 252 const std::vector<Value>& args, 253 Err* err); 254 255 extern const char kLabelMatches[]; 256 extern const char kLabelMatches_HelpShort[]; 257 extern const char kLabelMatches_Help[]; 258 Value RunLabelMatches(Scope* scope, 259 const FunctionCallNode* function, 260 const std::vector<Value>& args, 261 Err* err); 262 263 extern const char kLoadableModule[]; 264 extern const char kLoadableModule_HelpShort[]; 265 extern const char kLoadableModule_Help[]; 266 Value RunLoadableModule(Scope* scope, 267 const FunctionCallNode* function, 268 const std::vector<Value>& args, 269 BlockNode* block, 270 Err* err); 271 272 extern const char kNotNeeded[]; 273 extern const char kNotNeeded_HelpShort[]; 274 extern const char kNotNeeded_Help[]; 275 Value RunNotNeeded(Scope* scope, 276 const FunctionCallNode* function, 277 const ListNode* args_list, 278 Err* err); 279 280 extern const char kPool[]; 281 extern const char kPool_HelpShort[]; 282 extern const char kPool_Help[]; 283 Value RunPool(const FunctionCallNode* function, 284 const std::vector<Value>& args, 285 Scope* block_scope, 286 Err* err); 287 288 extern const char kPrint[]; 289 extern const char kPrint_HelpShort[]; 290 extern const char kPrint_Help[]; 291 Value RunPrint(Scope* scope, 292 const FunctionCallNode* function, 293 const std::vector<Value>& args, 294 Err* err); 295 296 extern const char kProcessFileTemplate[]; 297 extern const char kProcessFileTemplate_HelpShort[]; 298 extern const char kProcessFileTemplate_Help[]; 299 Value RunProcessFileTemplate(Scope* scope, 300 const FunctionCallNode* function, 301 const std::vector<Value>& args, 302 Err* err); 303 304 extern const char kReadFile[]; 305 extern const char kReadFile_HelpShort[]; 306 extern const char kReadFile_Help[]; 307 Value RunReadFile(Scope* scope, 308 const FunctionCallNode* function, 309 const std::vector<Value>& args, 310 Err* err); 311 312 extern const char kRebasePath[]; 313 extern const char kRebasePath_HelpShort[]; 314 extern const char kRebasePath_Help[]; 315 Value RunRebasePath(Scope* scope, 316 const FunctionCallNode* function, 317 const std::vector<Value>& args, 318 Err* err); 319 320 extern const char kRustLibrary[]; 321 extern const char kRustLibrary_HelpShort[]; 322 extern const char kRustLibrary_Help[]; 323 Value RunRustLibrary(Scope* scope, 324 const FunctionCallNode* function, 325 const std::vector<Value>& args, 326 BlockNode* block, 327 Err* err); 328 329 extern const char kRustProcMacro[]; 330 extern const char kRustProcMacro_HelpShort[]; 331 extern const char kRustProcMacro_Help[]; 332 Value RunRustProcMacro(Scope* scope, 333 const FunctionCallNode* function, 334 const std::vector<Value>& args, 335 BlockNode* block, 336 Err* err); 337 338 extern const char kSetDefaults[]; 339 extern const char kSetDefaults_HelpShort[]; 340 extern const char kSetDefaults_Help[]; 341 Value RunSetDefaults(Scope* scope, 342 const FunctionCallNode* function, 343 const std::vector<Value>& args, 344 BlockNode* block, 345 Err* err); 346 347 extern const char kSetDefaultToolchain[]; 348 extern const char kSetDefaultToolchain_HelpShort[]; 349 extern const char kSetDefaultToolchain_Help[]; 350 Value RunSetDefaultToolchain(Scope* scope, 351 const FunctionCallNode* function, 352 const std::vector<Value>& args, 353 Err* err); 354 355 extern const char kSharedLibrary[]; 356 extern const char kSharedLibrary_HelpShort[]; 357 extern const char kSharedLibrary_Help[]; 358 Value RunSharedLibrary(Scope* scope, 359 const FunctionCallNode* function, 360 const std::vector<Value>& args, 361 BlockNode* block, 362 Err* err); 363 364 extern const char kSourceSet[]; 365 extern const char kSourceSet_HelpShort[]; 366 extern const char kSourceSet_Help[]; 367 Value RunSourceSet(Scope* scope, 368 const FunctionCallNode* function, 369 const std::vector<Value>& args, 370 BlockNode* block, 371 Err* err); 372 373 extern const char kSplitList[]; 374 extern const char kSplitList_HelpShort[]; 375 extern const char kSplitList_Help[]; 376 Value RunSplitList(Scope* scope, 377 const FunctionCallNode* function, 378 const ListNode* args_list, 379 Err* err); 380 381 extern const char kStaticLibrary[]; 382 extern const char kStaticLibrary_HelpShort[]; 383 extern const char kStaticLibrary_Help[]; 384 Value RunStaticLibrary(Scope* scope, 385 const FunctionCallNode* function, 386 const std::vector<Value>& args, 387 BlockNode* block, 388 Err* err); 389 390 extern const char kReplaceSubstr[]; 391 extern const char kReplaceSubstr_HelpShort[]; 392 extern const char kReplaceSubstr_Help[]; 393 Value RunReplaceSubstr(Scope* scope, 394 const FunctionCallNode* function, 395 const std::vector<Value>& args_list, 396 Err* err); 397 398 extern const char kTarget[]; 399 extern const char kTarget_HelpShort[]; 400 extern const char kTarget_Help[]; 401 Value RunTarget(Scope* scope, 402 const FunctionCallNode* function, 403 const std::vector<Value>& args, 404 BlockNode* block, 405 Err* err); 406 407 extern const char kTemplate[]; 408 extern const char kTemplate_HelpShort[]; 409 extern const char kTemplate_Help[]; 410 Value RunTemplate(Scope* scope, 411 const FunctionCallNode* function, 412 const std::vector<Value>& args, 413 BlockNode* block, 414 Err* err); 415 416 extern const char kTool[]; 417 extern const char kTool_HelpShort[]; 418 extern const char kTool_Help[]; 419 Value RunTool(Scope* scope, 420 const FunctionCallNode* function, 421 const std::vector<Value>& args, 422 BlockNode* block, 423 Err* err); 424 425 extern const char kToolchain[]; 426 extern const char kToolchain_HelpShort[]; 427 extern const char kToolchain_Help[]; 428 Value RunToolchain(Scope* scope, 429 const FunctionCallNode* function, 430 const std::vector<Value>& args, 431 BlockNode* block, 432 Err* err); 433 434 extern const char kWriteFile[]; 435 extern const char kWriteFile_HelpShort[]; 436 extern const char kWriteFile_Help[]; 437 Value RunWriteFile(Scope* scope, 438 const FunctionCallNode* function, 439 const std::vector<Value>& args, 440 Err* err); 441 442 // ----------------------------------------------------------------------------- 443 444 // One function record. Only one of the given runner types will be non-null 445 // which indicates the type of function it is. 446 struct FunctionInfo { 447 FunctionInfo(); 448 FunctionInfo(SelfEvaluatingArgsFunction seaf, 449 const char* in_help_short, 450 const char* in_help, 451 bool in_is_target); 452 FunctionInfo(GenericBlockFunction gbf, 453 const char* in_help_short, 454 const char* in_help, 455 bool in_is_target); 456 FunctionInfo(ExecutedBlockFunction ebf, 457 const char* in_help_short, 458 const char* in_help, 459 bool in_is_target); 460 FunctionInfo(NoBlockFunction nbf, 461 const char* in_help_short, 462 const char* in_help, 463 bool in_is_target); 464 465 SelfEvaluatingArgsFunction self_evaluating_args_runner; 466 GenericBlockFunction generic_block_runner; 467 ExecutedBlockFunction executed_block_runner; 468 NoBlockFunction no_block_runner; 469 470 const char* help_short; 471 const char* help; 472 473 bool is_target; 474 }; 475 476 using FunctionInfoMap = std::map<std::string_view, FunctionInfo>; 477 478 // Returns the mapping of all built-in functions. 479 const FunctionInfoMap& GetFunctions(); 480 481 // Runs the given function. 482 Value RunFunction(Scope* scope, 483 const FunctionCallNode* function, 484 const ListNode* args_list, 485 BlockNode* block, // Optional. 486 Err* err); 487 488 } // namespace functions 489 490 // Helper functions ----------------------------------------------------------- 491 492 // Validates that the scope that a value is defined in is not the scope 493 // of the current declare_args() call, if that's what we're in. It is 494 // illegal to read a value from inside the same declare_args() call, since 495 // the overrides will not have been applied yet (see `gn help declare_args` 496 // for more). 497 bool EnsureNotReadingFromSameDeclareArgs(const ParseNode* node, 498 const Scope* cur_scope, 499 const Scope* val_scope, 500 Err* err); 501 502 // Verifies that the current scope is not processing an import. If it is, it 503 // will set the error, blame the given parse node for it, and return false. 504 bool EnsureNotProcessingImport(const ParseNode* node, 505 const Scope* scope, 506 Err* err); 507 508 // Like EnsureNotProcessingImport but checks for running the build config. 509 bool EnsureNotProcessingBuildConfig(const ParseNode* node, 510 const Scope* scope, 511 Err* err); 512 513 // Sets up the |block_scope| for executing a target (or something like it). 514 // The |scope| is the containing scope. It should have been already set as the 515 // parent for the |block_scope| when the |block_scope| was created. 516 // 517 // This will set up the target defaults and set the |target_name| variable in 518 // the block scope to the current target name, which is assumed to be the first 519 // argument to the function. 520 // 521 // On success, returns true. On failure, sets the error and returns false. 522 bool FillTargetBlockScope(const Scope* scope, 523 const FunctionCallNode* function, 524 const std::string& target_type, 525 const BlockNode* block, 526 const std::vector<Value>& args, 527 Scope* block_scope, 528 Err* err); 529 530 // Sets the given error to a message explaining that the function call requires 531 // a block. 532 void FillNeedsBlockError(const FunctionCallNode* function, Err* err); 533 534 // Validates that the given function call has one string argument. This is 535 // the most common function signature, so it saves space to have this helper. 536 // Returns false and sets the error on failure. 537 bool EnsureSingleStringArg(const FunctionCallNode* function, 538 const std::vector<Value>& args, 539 Err* err); 540 541 // Returns the name of the toolchain for the given scope. 542 const Label& ToolchainLabelForScope(const Scope* scope); 543 544 // Generates a label for the given scope, using the current directory and 545 // toolchain, and the given name. 546 Label MakeLabelForScope(const Scope* scope, 547 const FunctionCallNode* function, 548 const std::string& name); 549 550 // Some types of blocks can't be nested inside other ones. For such cases, 551 // instantiate this object upon entering the block and Enter() will fail if 552 // there is already another non-nestable block on the stack. 553 class NonNestableBlock { 554 public: 555 // type_description is a string that will be used in error messages 556 // describing the type of the block, for example, "template" or "config". 557 NonNestableBlock(Scope* scope, 558 const FunctionCallNode* function, 559 const char* type_description); 560 ~NonNestableBlock(); 561 562 bool Enter(Err* err); 563 564 private: 565 // Used as a void* key for the Scope to track our property. The actual value 566 // is never used. 567 static const int kKey; 568 569 Scope* scope_; 570 const FunctionCallNode* function_; 571 const char* type_description_; 572 573 // Set to true when the key is added to the scope so we don't try to 574 // delete nonexistent keys which will cause assertions. 575 bool key_added_; 576 }; 577 578 #endif // TOOLS_GN_FUNCTIONS_H_ 579