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 <vector> 11 12 #include "base/strings/string_piece.h" 13 14 class Err; 15 class BlockNode; 16 class FunctionCallNode; 17 class Label; 18 class ListNode; 19 class ParseNode; 20 class Scope; 21 class Value; 22 23 // ----------------------------------------------------------------------------- 24 25 namespace functions { 26 27 // This type of function invocation has no block and evaluates its arguments 28 // itself rather than taking a pre-executed list. This allows us to implement 29 // certain built-in functions. 30 typedef Value (*SelfEvaluatingArgsFunction)(Scope* scope, 31 const FunctionCallNode* function, 32 const ListNode* args_list, 33 Err* err); 34 35 // This type of function invocation takes a block node that it will execute. 36 typedef Value (*GenericBlockFunction)(Scope* scope, 37 const FunctionCallNode* function, 38 const std::vector<Value>& args, 39 BlockNode* block, 40 Err* err); 41 42 // This type of function takes a block, but does not need to control execution 43 // of it. The dispatch function will pre-execute the block and pass the 44 // resulting block_scope to the function. 45 typedef Value (*ExecutedBlockFunction)(const FunctionCallNode* function, 46 const std::vector<Value>& args, 47 Scope* block_scope, 48 Err* err); 49 50 // This type of function does not take a block. It just has arguments. 51 typedef Value (*NoBlockFunction)(Scope* scope, 52 const FunctionCallNode* function, 53 const std::vector<Value>& args, 54 Err* err); 55 56 extern const char kAction[]; 57 extern const char kAction_HelpShort[]; 58 extern const char kAction_Help[]; 59 Value RunAction(Scope* scope, 60 const FunctionCallNode* function, 61 const std::vector<Value>& args, 62 BlockNode* block, 63 Err* err); 64 65 extern const char kActionForEach[]; 66 extern const char kActionForEach_HelpShort[]; 67 extern const char kActionForEach_Help[]; 68 Value RunActionForEach(Scope* scope, 69 const FunctionCallNode* function, 70 const std::vector<Value>& args, 71 BlockNode* block, 72 Err* err); 73 74 extern const char kAssert[]; 75 extern const char kAssert_HelpShort[]; 76 extern const char kAssert_Help[]; 77 Value RunAssert(Scope* scope, 78 const FunctionCallNode* function, 79 const std::vector<Value>& args, 80 Err* err); 81 82 extern const char kBundleData[]; 83 extern const char kBundleData_HelpShort[]; 84 extern const char kBundleData_Help[]; 85 Value RunBundleData(Scope* scope, 86 const FunctionCallNode* function, 87 const std::vector<Value>& args, 88 BlockNode* block, 89 Err* err); 90 91 extern const char kCreateBundle[]; 92 extern const char kCreateBundle_HelpShort[]; 93 extern const char kCreateBundle_Help[]; 94 Value RunCreateBundle(Scope* scope, 95 const FunctionCallNode* function, 96 const std::vector<Value>& args, 97 BlockNode* block, 98 Err* err); 99 100 extern const char kConfig[]; 101 extern const char kConfig_HelpShort[]; 102 extern const char kConfig_Help[]; 103 Value RunConfig(const FunctionCallNode* function, 104 const std::vector<Value>& args, 105 Scope* block_scope, 106 Err* err); 107 108 extern const char kCopy[]; 109 extern const char kCopy_HelpShort[]; 110 extern const char kCopy_Help[]; 111 Value RunCopy(const FunctionCallNode* function, 112 const std::vector<Value>& args, 113 Scope* block_scope, 114 Err* err); 115 116 extern const char kDeclareArgs[]; 117 extern const char kDeclareArgs_HelpShort[]; 118 extern const char kDeclareArgs_Help[]; 119 Value RunDeclareArgs(Scope* scope, 120 const FunctionCallNode* function, 121 const std::vector<Value>& args, 122 BlockNode* block, 123 Err* err); 124 125 extern const char kDefined[]; 126 extern const char kDefined_HelpShort[]; 127 extern const char kDefined_Help[]; 128 Value RunDefined(Scope* scope, 129 const FunctionCallNode* function, 130 const ListNode* args_list, 131 Err* err); 132 133 extern const char kExecScript[]; 134 extern const char kExecScript_HelpShort[]; 135 extern const char kExecScript_Help[]; 136 Value RunExecScript(Scope* scope, 137 const FunctionCallNode* function, 138 const std::vector<Value>& args, 139 Err* err); 140 141 extern const char kExecutable[]; 142 extern const char kExecutable_HelpShort[]; 143 extern const char kExecutable_Help[]; 144 Value RunExecutable(Scope* scope, 145 const FunctionCallNode* function, 146 const std::vector<Value>& args, 147 BlockNode* block, 148 Err* err); 149 150 extern const char kFilterExclude[]; 151 extern const char kFilterExclude_HelpShort[]; 152 extern const char kFilterExclude_Help[]; 153 Value RunFilterExclude(Scope* scope, 154 const FunctionCallNode* function, 155 const std::vector<Value>& args, 156 Err* err); 157 158 extern const char kFilterInclude[]; 159 extern const char kFilterInclude_HelpShort[]; 160 extern const char kFilterInclude_Help[]; 161 Value RunFilterInclude(Scope* scope, 162 const FunctionCallNode* function, 163 const std::vector<Value>& args, 164 Err* err); 165 166 extern const char kForEach[]; 167 extern const char kForEach_HelpShort[]; 168 extern const char kForEach_Help[]; 169 Value RunForEach(Scope* scope, 170 const FunctionCallNode* function, 171 const ListNode* args_list, 172 Err* err); 173 174 extern const char kForwardVariablesFrom[]; 175 extern const char kForwardVariablesFrom_HelpShort[]; 176 extern const char kForwardVariablesFrom_Help[]; 177 Value RunForwardVariablesFrom(Scope* scope, 178 const FunctionCallNode* function, 179 const ListNode* args_list, 180 Err* err); 181 182 extern const char kGetEnv[]; 183 extern const char kGetEnv_HelpShort[]; 184 extern const char kGetEnv_Help[]; 185 Value RunGetEnv(Scope* scope, 186 const FunctionCallNode* function, 187 const std::vector<Value>& args, 188 Err* err); 189 190 extern const char kGetLabelInfo[]; 191 extern const char kGetLabelInfo_HelpShort[]; 192 extern const char kGetLabelInfo_Help[]; 193 Value RunGetLabelInfo(Scope* scope, 194 const FunctionCallNode* function, 195 const std::vector<Value>& args, 196 Err* err); 197 198 extern const char kGetPathInfo[]; 199 extern const char kGetPathInfo_HelpShort[]; 200 extern const char kGetPathInfo_Help[]; 201 Value RunGetPathInfo(Scope* scope, 202 const FunctionCallNode* function, 203 const std::vector<Value>& args, 204 Err* err); 205 206 extern const char kGetTargetOutputs[]; 207 extern const char kGetTargetOutputs_HelpShort[]; 208 extern const char kGetTargetOutputs_Help[]; 209 Value RunGetTargetOutputs(Scope* scope, 210 const FunctionCallNode* function, 211 const std::vector<Value>& args, 212 Err* err); 213 214 extern const char kGeneratedFile[]; 215 extern const char kGeneratedFile_HelpShort[]; 216 extern const char kGeneratedFile_Help[]; 217 Value RunGeneratedFile(Scope* scope, 218 const FunctionCallNode* function, 219 const std::vector<Value>& args, 220 BlockNode* block, 221 Err* err); 222 223 extern const char kGroup[]; 224 extern const char kGroup_HelpShort[]; 225 extern const char kGroup_Help[]; 226 Value RunGroup(Scope* scope, 227 const FunctionCallNode* function, 228 const std::vector<Value>& args, 229 BlockNode* block, 230 Err* err); 231 232 extern const char kImport[]; 233 extern const char kImport_HelpShort[]; 234 extern const char kImport_Help[]; 235 Value RunImport(Scope* scope, 236 const FunctionCallNode* function, 237 const std::vector<Value>& args, 238 Err* err); 239 240 extern const char kLoadableModule[]; 241 extern const char kLoadableModule_HelpShort[]; 242 extern const char kLoadableModule_Help[]; 243 Value RunLoadableModule(Scope* scope, 244 const FunctionCallNode* function, 245 const std::vector<Value>& args, 246 BlockNode* block, 247 Err* err); 248 249 extern const char kNotNeeded[]; 250 extern const char kNotNeeded_HelpShort[]; 251 extern const char kNotNeeded_Help[]; 252 Value RunNotNeeded(Scope* scope, 253 const FunctionCallNode* function, 254 const ListNode* args_list, 255 Err* err); 256 257 extern const char kPool[]; 258 extern const char kPool_HelpShort[]; 259 extern const char kPool_Help[]; 260 Value RunPool(const FunctionCallNode* function, 261 const std::vector<Value>& args, 262 Scope* block_scope, 263 Err* err); 264 265 extern const char kPrint[]; 266 extern const char kPrint_HelpShort[]; 267 extern const char kPrint_Help[]; 268 Value RunPrint(Scope* scope, 269 const FunctionCallNode* function, 270 const std::vector<Value>& args, 271 Err* err); 272 273 extern const char kProcessFileTemplate[]; 274 extern const char kProcessFileTemplate_HelpShort[]; 275 extern const char kProcessFileTemplate_Help[]; 276 Value RunProcessFileTemplate(Scope* scope, 277 const FunctionCallNode* function, 278 const std::vector<Value>& args, 279 Err* err); 280 281 extern const char kReadFile[]; 282 extern const char kReadFile_HelpShort[]; 283 extern const char kReadFile_Help[]; 284 Value RunReadFile(Scope* scope, 285 const FunctionCallNode* function, 286 const std::vector<Value>& args, 287 Err* err); 288 289 extern const char kRebasePath[]; 290 extern const char kRebasePath_HelpShort[]; 291 extern const char kRebasePath_Help[]; 292 Value RunRebasePath(Scope* scope, 293 const FunctionCallNode* function, 294 const std::vector<Value>& args, 295 Err* err); 296 297 extern const char kRustLibrary[]; 298 extern const char kRustLibrary_HelpShort[]; 299 extern const char kRustLibrary_Help[]; 300 Value RunRustLibrary(Scope* scope, 301 const FunctionCallNode* function, 302 const std::vector<Value>& args, 303 BlockNode* block, 304 Err* err); 305 306 extern const char kSetDefaults[]; 307 extern const char kSetDefaults_HelpShort[]; 308 extern const char kSetDefaults_Help[]; 309 Value RunSetDefaults(Scope* scope, 310 const FunctionCallNode* function, 311 const std::vector<Value>& args, 312 BlockNode* block, 313 Err* err); 314 315 extern const char kSetDefaultToolchain[]; 316 extern const char kSetDefaultToolchain_HelpShort[]; 317 extern const char kSetDefaultToolchain_Help[]; 318 Value RunSetDefaultToolchain(Scope* scope, 319 const FunctionCallNode* function, 320 const std::vector<Value>& args, 321 Err* err); 322 323 extern const char kSetSourcesAssignmentFilter[]; 324 extern const char kSetSourcesAssignmentFilter_HelpShort[]; 325 extern const char kSetSourcesAssignmentFilter_Help[]; 326 Value RunSetSourcesAssignmentFilter(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 typedef std::map<base::StringPiece, FunctionInfo> FunctionInfoMap; 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 nonexistant keys which will cause assertions. 551 bool key_added_; 552 }; 553 554 #endif // TOOLS_GN_FUNCTIONS_H_ 555