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