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 kForEach[]; 166 extern const char kForEach_HelpShort[]; 167 extern const char kForEach_Help[]; 168 Value RunForEach(Scope* scope, 169 const FunctionCallNode* function, 170 const ListNode* args_list, 171 Err* err); 172 173 extern const char kForwardVariablesFrom[]; 174 extern const char kForwardVariablesFrom_HelpShort[]; 175 extern const char kForwardVariablesFrom_Help[]; 176 Value RunForwardVariablesFrom(Scope* scope, 177 const FunctionCallNode* function, 178 const ListNode* args_list, 179 Err* err); 180 181 extern const char kGetEnv[]; 182 extern const char kGetEnv_HelpShort[]; 183 extern const char kGetEnv_Help[]; 184 Value RunGetEnv(Scope* scope, 185 const FunctionCallNode* function, 186 const std::vector<Value>& args, 187 Err* err); 188 189 extern const char kGetLabelInfo[]; 190 extern const char kGetLabelInfo_HelpShort[]; 191 extern const char kGetLabelInfo_Help[]; 192 Value RunGetLabelInfo(Scope* scope, 193 const FunctionCallNode* function, 194 const std::vector<Value>& args, 195 Err* err); 196 197 extern const char kGetPathInfo[]; 198 extern const char kGetPathInfo_HelpShort[]; 199 extern const char kGetPathInfo_Help[]; 200 Value RunGetPathInfo(Scope* scope, 201 const FunctionCallNode* function, 202 const std::vector<Value>& args, 203 Err* err); 204 205 extern const char kGetTargetOutputs[]; 206 extern const char kGetTargetOutputs_HelpShort[]; 207 extern const char kGetTargetOutputs_Help[]; 208 Value RunGetTargetOutputs(Scope* scope, 209 const FunctionCallNode* function, 210 const std::vector<Value>& args, 211 Err* err); 212 213 extern const char kGeneratedFile[]; 214 extern const char kGeneratedFile_HelpShort[]; 215 extern const char kGeneratedFile_Help[]; 216 Value RunGeneratedFile(Scope* scope, 217 const FunctionCallNode* function, 218 const std::vector<Value>& args, 219 BlockNode* block, 220 Err* err); 221 222 extern const char kGroup[]; 223 extern const char kGroup_HelpShort[]; 224 extern const char kGroup_Help[]; 225 Value RunGroup(Scope* scope, 226 const FunctionCallNode* function, 227 const std::vector<Value>& args, 228 BlockNode* block, 229 Err* err); 230 231 extern const char kImport[]; 232 extern const char kImport_HelpShort[]; 233 extern const char kImport_Help[]; 234 Value RunImport(Scope* scope, 235 const FunctionCallNode* function, 236 const std::vector<Value>& args, 237 Err* err); 238 239 extern const char kLoadableModule[]; 240 extern const char kLoadableModule_HelpShort[]; 241 extern const char kLoadableModule_Help[]; 242 Value RunLoadableModule(Scope* scope, 243 const FunctionCallNode* function, 244 const std::vector<Value>& args, 245 BlockNode* block, 246 Err* err); 247 248 extern const char kNotNeeded[]; 249 extern const char kNotNeeded_HelpShort[]; 250 extern const char kNotNeeded_Help[]; 251 Value RunNotNeeded(Scope* scope, 252 const FunctionCallNode* function, 253 const ListNode* args_list, 254 Err* err); 255 256 extern const char kPool[]; 257 extern const char kPool_HelpShort[]; 258 extern const char kPool_Help[]; 259 Value RunPool(const FunctionCallNode* function, 260 const std::vector<Value>& args, 261 Scope* block_scope, 262 Err* err); 263 264 extern const char kPrint[]; 265 extern const char kPrint_HelpShort[]; 266 extern const char kPrint_Help[]; 267 Value RunPrint(Scope* scope, 268 const FunctionCallNode* function, 269 const std::vector<Value>& args, 270 Err* err); 271 272 extern const char kProcessFileTemplate[]; 273 extern const char kProcessFileTemplate_HelpShort[]; 274 extern const char kProcessFileTemplate_Help[]; 275 Value RunProcessFileTemplate(Scope* scope, 276 const FunctionCallNode* function, 277 const std::vector<Value>& args, 278 Err* err); 279 280 extern const char kReadFile[]; 281 extern const char kReadFile_HelpShort[]; 282 extern const char kReadFile_Help[]; 283 Value RunReadFile(Scope* scope, 284 const FunctionCallNode* function, 285 const std::vector<Value>& args, 286 Err* err); 287 288 extern const char kRebasePath[]; 289 extern const char kRebasePath_HelpShort[]; 290 extern const char kRebasePath_Help[]; 291 Value RunRebasePath(Scope* scope, 292 const FunctionCallNode* function, 293 const std::vector<Value>& args, 294 Err* err); 295 296 extern const char kRustLibrary[]; 297 extern const char kRustLibrary_HelpShort[]; 298 extern const char kRustLibrary_Help[]; 299 Value RunRustLibrary(Scope* scope, 300 const FunctionCallNode* function, 301 const std::vector<Value>& args, 302 BlockNode* block, 303 Err* err); 304 305 extern const char kRustProcMacro[]; 306 extern const char kRustProcMacro_HelpShort[]; 307 extern const char kRustProcMacro_Help[]; 308 Value RunRustProcMacro(Scope* scope, 309 const FunctionCallNode* function, 310 const std::vector<Value>& args, 311 BlockNode* block, 312 Err* err); 313 314 extern const char kSetDefaults[]; 315 extern const char kSetDefaults_HelpShort[]; 316 extern const char kSetDefaults_Help[]; 317 Value RunSetDefaults(Scope* scope, 318 const FunctionCallNode* function, 319 const std::vector<Value>& args, 320 BlockNode* block, 321 Err* err); 322 323 extern const char kSetDefaultToolchain[]; 324 extern const char kSetDefaultToolchain_HelpShort[]; 325 extern const char kSetDefaultToolchain_Help[]; 326 Value RunSetDefaultToolchain(Scope* scope, 327 const FunctionCallNode* function, 328 const std::vector<Value>& args, 329 Err* err); 330 331 extern const char kSharedLibrary[]; 332 extern const char kSharedLibrary_HelpShort[]; 333 extern const char kSharedLibrary_Help[]; 334 Value RunSharedLibrary(Scope* scope, 335 const FunctionCallNode* function, 336 const std::vector<Value>& args, 337 BlockNode* block, 338 Err* err); 339 340 extern const char kSourceSet[]; 341 extern const char kSourceSet_HelpShort[]; 342 extern const char kSourceSet_Help[]; 343 Value RunSourceSet(Scope* scope, 344 const FunctionCallNode* function, 345 const std::vector<Value>& args, 346 BlockNode* block, 347 Err* err); 348 349 extern const char kSplitList[]; 350 extern const char kSplitList_HelpShort[]; 351 extern const char kSplitList_Help[]; 352 Value RunSplitList(Scope* scope, 353 const FunctionCallNode* function, 354 const ListNode* args_list, 355 Err* err); 356 357 extern const char kStaticLibrary[]; 358 extern const char kStaticLibrary_HelpShort[]; 359 extern const char kStaticLibrary_Help[]; 360 Value RunStaticLibrary(Scope* scope, 361 const FunctionCallNode* function, 362 const std::vector<Value>& args, 363 BlockNode* block, 364 Err* err); 365 366 extern const char kReplaceSubstr[]; 367 extern const char kReplaceSubstr_HelpShort[]; 368 extern const char kReplaceSubstr_Help[]; 369 Value RunReplaceSubstr(Scope* scope, 370 const FunctionCallNode* function, 371 const std::vector<Value>& args_list, 372 Err* err); 373 374 extern const char kTarget[]; 375 extern const char kTarget_HelpShort[]; 376 extern const char kTarget_Help[]; 377 Value RunTarget(Scope* scope, 378 const FunctionCallNode* function, 379 const std::vector<Value>& args, 380 BlockNode* block, 381 Err* err); 382 383 extern const char kTemplate[]; 384 extern const char kTemplate_HelpShort[]; 385 extern const char kTemplate_Help[]; 386 Value RunTemplate(Scope* scope, 387 const FunctionCallNode* function, 388 const std::vector<Value>& args, 389 BlockNode* block, 390 Err* err); 391 392 extern const char kTool[]; 393 extern const char kTool_HelpShort[]; 394 extern const char kTool_Help[]; 395 Value RunTool(Scope* scope, 396 const FunctionCallNode* function, 397 const std::vector<Value>& args, 398 BlockNode* block, 399 Err* err); 400 401 extern const char kToolchain[]; 402 extern const char kToolchain_HelpShort[]; 403 extern const char kToolchain_Help[]; 404 Value RunToolchain(Scope* scope, 405 const FunctionCallNode* function, 406 const std::vector<Value>& args, 407 BlockNode* block, 408 Err* err); 409 410 extern const char kWriteFile[]; 411 extern const char kWriteFile_HelpShort[]; 412 extern const char kWriteFile_Help[]; 413 Value RunWriteFile(Scope* scope, 414 const FunctionCallNode* function, 415 const std::vector<Value>& args, 416 Err* err); 417 418 // ----------------------------------------------------------------------------- 419 420 // One function record. Only one of the given runner types will be non-null 421 // which indicates the type of function it is. 422 struct FunctionInfo { 423 FunctionInfo(); 424 FunctionInfo(SelfEvaluatingArgsFunction seaf, 425 const char* in_help_short, 426 const char* in_help, 427 bool in_is_target); 428 FunctionInfo(GenericBlockFunction gbf, 429 const char* in_help_short, 430 const char* in_help, 431 bool in_is_target); 432 FunctionInfo(ExecutedBlockFunction ebf, 433 const char* in_help_short, 434 const char* in_help, 435 bool in_is_target); 436 FunctionInfo(NoBlockFunction nbf, 437 const char* in_help_short, 438 const char* in_help, 439 bool in_is_target); 440 441 SelfEvaluatingArgsFunction self_evaluating_args_runner; 442 GenericBlockFunction generic_block_runner; 443 ExecutedBlockFunction executed_block_runner; 444 NoBlockFunction no_block_runner; 445 446 const char* help_short; 447 const char* help; 448 449 bool is_target; 450 }; 451 452 using FunctionInfoMap = std::map<std::string_view, FunctionInfo>; 453 454 // Returns the mapping of all built-in functions. 455 const FunctionInfoMap& GetFunctions(); 456 457 // Runs the given function. 458 Value RunFunction(Scope* scope, 459 const FunctionCallNode* function, 460 const ListNode* args_list, 461 BlockNode* block, // Optional. 462 Err* err); 463 464 } // namespace functions 465 466 // Helper functions ----------------------------------------------------------- 467 468 // Validates that the scope that a value is defined in is not the scope 469 // of the current declare_args() call, if that's what we're in. It is 470 // illegal to read a value from inside the same declare_args() call, since 471 // the overrides will not have been applied yet (see `gn help declare_args` 472 // for more). 473 bool EnsureNotReadingFromSameDeclareArgs(const ParseNode* node, 474 const Scope* cur_scope, 475 const Scope* val_scope, 476 Err* err); 477 478 // Verifies that the current scope is not processing an import. If it is, it 479 // will set the error, blame the given parse node for it, and return false. 480 bool EnsureNotProcessingImport(const ParseNode* node, 481 const Scope* scope, 482 Err* err); 483 484 // Like EnsureNotProcessingImport but checks for running the build config. 485 bool EnsureNotProcessingBuildConfig(const ParseNode* node, 486 const Scope* scope, 487 Err* err); 488 489 // Sets up the |block_scope| for executing a target (or something like it). 490 // The |scope| is the containing scope. It should have been already set as the 491 // parent for the |block_scope| when the |block_scope| was created. 492 // 493 // This will set up the target defaults and set the |target_name| variable in 494 // the block scope to the current target name, which is assumed to be the first 495 // argument to the function. 496 // 497 // On success, returns true. On failure, sets the error and returns false. 498 bool FillTargetBlockScope(const Scope* scope, 499 const FunctionCallNode* function, 500 const std::string& target_type, 501 const BlockNode* block, 502 const std::vector<Value>& args, 503 Scope* block_scope, 504 Err* err); 505 506 // Sets the given error to a message explaining that the function call requires 507 // a block. 508 void FillNeedsBlockError(const FunctionCallNode* function, Err* err); 509 510 // Validates that the given function call has one string argument. This is 511 // the most common function signature, so it saves space to have this helper. 512 // Returns false and sets the error on failure. 513 bool EnsureSingleStringArg(const FunctionCallNode* function, 514 const std::vector<Value>& args, 515 Err* err); 516 517 // Returns the name of the toolchain for the given scope. 518 const Label& ToolchainLabelForScope(const Scope* scope); 519 520 // Generates a label for the given scope, using the current directory and 521 // toolchain, and the given name. 522 Label MakeLabelForScope(const Scope* scope, 523 const FunctionCallNode* function, 524 const std::string& name); 525 526 // Some types of blocks can't be nested inside other ones. For such cases, 527 // instantiate this object upon entering the block and Enter() will fail if 528 // there is already another non-nestable block on the stack. 529 class NonNestableBlock { 530 public: 531 // type_description is a string that will be used in error messages 532 // describing the type of the block, for example, "template" or "config". 533 NonNestableBlock(Scope* scope, 534 const FunctionCallNode* function, 535 const char* type_description); 536 ~NonNestableBlock(); 537 538 bool Enter(Err* err); 539 540 private: 541 // Used as a void* key for the Scope to track our property. The actual value 542 // is never used. 543 static const int kKey; 544 545 Scope* scope_; 546 const FunctionCallNode* function_; 547 const char* type_description_; 548 549 // Set to true when the key is added to the scope so we don't try to 550 // delete nonexistent keys which will cause assertions. 551 bool key_added_; 552 }; 553 554 #endif // TOOLS_GN_FUNCTIONS_H_ 555