tools/gn/functions.h

   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 Token;
  22 class Value;
  23
  24 // -----------------------------------------------------------------------------
  25
  26 namespace functions {
  27
  28 // This type of function invocation has no block and evaluates its arguments
  29 // itself rather than taking a pre-executed list. This allows us to implement
  30 // certain built-in functions.
  31 typedef Value (*SelfEvaluatingArgsFunction)(Scope* scope,
  32                                             const FunctionCallNode* function,
  33                                             const ListNode* args_list,
  34                                             Err* err);
  35
  36 // This type of function invocation takes a block node that it will execute.
  37 typedef Value (*GenericBlockFunction)(Scope* scope,
  38                                       const FunctionCallNode* function,
  39                                       const std::vector<Value>& args,
  40                                       BlockNode* block,
  41                                       Err* err);
  42
  43 // This type of function takes a block, but does not need to control execution
  44 // of it. The dispatch function will pre-execute the block and pass the
  45 // resulting block_scope to the function.
  46 typedef Value(*ExecutedBlockFunction)(const FunctionCallNode* function,
  47                                       const std::vector<Value>& args,
  48                                       Scope* block_scope,
  49                                       Err* err);
  50
  51 // This type of function does not take a block. It just has arguments.
  52 typedef Value (*NoBlockFunction)(Scope* scope,
  53                                  const FunctionCallNode* function,
  54                                  const std::vector<Value>& args,
  55                                  Err* err);
  56
  57 extern const char kAction[];
  58 extern const char kAction_HelpShort[];
  59 extern const char kAction_Help[];
  60 Value RunAction(Scope* scope,
  61                 const FunctionCallNode* function,
  62                 const std::vector<Value>& args,
  63                 BlockNode* block,
  64                 Err* err);
  65
  66 extern const char kActionForEach[];
  67 extern const char kActionForEach_HelpShort[];
  68 extern const char kActionForEach_Help[];
  69 Value RunActionForEach(Scope* scope,
  70                        const FunctionCallNode* function,
  71                        const std::vector<Value>& args,
  72                        BlockNode* block,
  73                        Err* err);
  74
  75 extern const char kAssert[];
  76 extern const char kAssert_HelpShort[];
  77 extern const char kAssert_Help[];
  78 Value RunAssert(Scope* scope,
  79                 const FunctionCallNode* function,
  80                 const std::vector<Value>& args,
  81                 Err* err);
  82
  83 extern const char kConfig[];
  84 extern const char kConfig_HelpShort[];
  85 extern const char kConfig_Help[];
  86 Value RunConfig(const FunctionCallNode* function,
  87                 const std::vector<Value>& args,
  88                 Scope* block_scope,
  89                 Err* err);
  90
  91 extern const char kCopy[];
  92 extern const char kCopy_HelpShort[];
  93 extern const char kCopy_Help[];
  94 Value RunCopy(const FunctionCallNode* function,
  95               const std::vector<Value>& args,
  96               Scope* block_scope,
  97               Err* err);
  98
  99 extern const char kDeclareArgs[];
 100 extern const char kDeclareArgs_HelpShort[];
 101 extern const char kDeclareArgs_Help[];
 102 Value RunDeclareArgs(Scope* scope,
 103                      const FunctionCallNode* function,
 104                      const std::vector<Value>& args,
 105                      BlockNode* block,
 106                      Err* err);
 107
 108 extern const char kDefined[];
 109 extern const char kDefined_HelpShort[];
 110 extern const char kDefined_Help[];
 111 Value RunDefined(Scope* scope,
 112                  const FunctionCallNode* function,
 113                  const ListNode* args_list,
 114                  Err* err);
 115
 116 extern const char kExecScript[];
 117 extern const char kExecScript_HelpShort[];
 118 extern const char kExecScript_Help[];
 119 Value RunExecScript(Scope* scope,
 120                     const FunctionCallNode* function,
 121                     const std::vector<Value>& args,
 122                     Err* err);
 123
 124 extern const char kExecutable[];
 125 extern const char kExecutable_HelpShort[];
 126 extern const char kExecutable_Help[];
 127 Value RunExecutable(Scope* scope,
 128                     const FunctionCallNode* function,
 129                     const std::vector<Value>& args,
 130                     BlockNode* block,
 131                     Err* err);
 132
 133 extern const char kForEach[];
 134 extern const char kForEach_HelpShort[];
 135 extern const char kForEach_Help[];
 136 Value RunForEach(Scope* scope,
 137                  const FunctionCallNode* function,
 138                  const ListNode* args_list,
 139                  Err* err);
 140
 141 extern const char kForwardVariablesFrom[];
 142 extern const char kForwardVariablesFrom_HelpShort[];
 143 extern const char kForwardVariablesFrom_Help[];
 144 Value RunForwardVariablesFrom(Scope* scope,
 145                               const FunctionCallNode* function,
 146                               const ListNode* args_list,
 147                               Err* err);
 148
 149 extern const char kGetEnv[];
 150 extern const char kGetEnv_HelpShort[];
 151 extern const char kGetEnv_Help[];
 152 Value RunGetEnv(Scope* scope,
 153                 const FunctionCallNode* function,
 154                 const std::vector<Value>& args,
 155                 Err* err);
 156
 157 extern const char kGetLabelInfo[];
 158 extern const char kGetLabelInfo_HelpShort[];
 159 extern const char kGetLabelInfo_Help[];
 160 Value RunGetLabelInfo(Scope* scope,
 161                       const FunctionCallNode* function,
 162                       const std::vector<Value>& args,
 163                       Err* err);
 164
 165 extern const char kGetPathInfo[];
 166 extern const char kGetPathInfo_HelpShort[];
 167 extern const char kGetPathInfo_Help[];
 168 Value RunGetPathInfo(Scope* scope,
 169                      const FunctionCallNode* function,
 170                      const std::vector<Value>& args,
 171                      Err* err);
 172
 173 extern const char kGetTargetOutputs[];
 174 extern const char kGetTargetOutputs_HelpShort[];
 175 extern const char kGetTargetOutputs_Help[];
 176 Value RunGetTargetOutputs(Scope* scope,
 177                           const FunctionCallNode* function,
 178                           const std::vector<Value>& args,
 179                           Err* err);
 180
 181 extern const char kGroup[];
 182 extern const char kGroup_HelpShort[];
 183 extern const char kGroup_Help[];
 184 Value RunGroup(Scope* scope,
 185                const FunctionCallNode* function,
 186                const std::vector<Value>& args,
 187                BlockNode* block,
 188                Err* err);
 189
 190 extern const char kImport[];
 191 extern const char kImport_HelpShort[];
 192 extern const char kImport_Help[];
 193 Value RunImport(Scope* scope,
 194                 const FunctionCallNode* function,
 195                 const std::vector<Value>& args,
 196                 Err* err);
 197
 198 extern const char kPrint[];
 199 extern const char kPrint_HelpShort[];
 200 extern const char kPrint_Help[];
 201 Value RunPrint(Scope* scope,
 202                const FunctionCallNode* function,
 203                const std::vector<Value>& args,
 204                Err* err);
 205
 206 extern const char kProcessFileTemplate[];
 207 extern const char kProcessFileTemplate_HelpShort[];
 208 extern const char kProcessFileTemplate_Help[];
 209 Value RunProcessFileTemplate(Scope* scope,
 210                              const FunctionCallNode* function,
 211                              const std::vector<Value>& args,
 212                              Err* err);
 213
 214 extern const char kReadFile[];
 215 extern const char kReadFile_HelpShort[];
 216 extern const char kReadFile_Help[];
 217 Value RunReadFile(Scope* scope,
 218                   const FunctionCallNode* function,
 219                   const std::vector<Value>& args,
 220                   Err* err);
 221
 222 extern const char kRebasePath[];
 223 extern const char kRebasePath_HelpShort[];
 224 extern const char kRebasePath_Help[];
 225 Value RunRebasePath(Scope* scope,
 226                     const FunctionCallNode* function,
 227                     const std::vector<Value>& args,
 228                     Err* err);
 229
 230 extern const char kSetDefaults[];
 231 extern const char kSetDefaults_HelpShort[];
 232 extern const char kSetDefaults_Help[];
 233 Value RunSetDefaults(Scope* scope,
 234                      const FunctionCallNode* function,
 235                      const std::vector<Value>& args,
 236                      BlockNode* block,
 237                      Err* err);
 238
 239 extern const char kSetDefaultToolchain[];
 240 extern const char kSetDefaultToolchain_HelpShort[];
 241 extern const char kSetDefaultToolchain_Help[];
 242 Value RunSetDefaultToolchain(Scope* scope,
 243                              const FunctionCallNode* function,
 244                              const std::vector<Value>& args,
 245                              Err* err);
 246
 247 extern const char kSetSourcesAssignmentFilter[];
 248 extern const char kSetSourcesAssignmentFilter_HelpShort[];
 249 extern const char kSetSourcesAssignmentFilter_Help[];
 250 Value RunSetSourcesAssignmentFilter(Scope* scope,
 251                                     const FunctionCallNode* function,
 252                                     const std::vector<Value>& args,
 253                                     Err* err);
 254
 255 extern const char kSharedLibrary[];
 256 extern const char kSharedLibrary_HelpShort[];
 257 extern const char kSharedLibrary_Help[];
 258 Value RunSharedLibrary(Scope* scope,
 259                        const FunctionCallNode* function,
 260                        const std::vector<Value>& args,
 261                        BlockNode* block,
 262                        Err* err);
 263
 264 extern const char kSourceSet[];
 265 extern const char kSourceSet_HelpShort[];
 266 extern const char kSourceSet_Help[];
 267 Value RunSourceSet(Scope* scope,
 268                    const FunctionCallNode* function,
 269                    const std::vector<Value>& args,
 270                    BlockNode* block,
 271                    Err* err);
 272
 273 extern const char kStaticLibrary[];
 274 extern const char kStaticLibrary_HelpShort[];
 275 extern const char kStaticLibrary_Help[];
 276 Value RunStaticLibrary(Scope* scope,
 277                        const FunctionCallNode* function,
 278                        const std::vector<Value>& args,
 279                        BlockNode* block,
 280                        Err* err);
 281
 282 extern const char kTarget[];
 283 extern const char kTarget_HelpShort[];
 284 extern const char kTarget_Help[];
 285 Value RunTarget(Scope* scope,
 286                 const FunctionCallNode* function,
 287                 const std::vector<Value>& args,
 288                 BlockNode* block,
 289                 Err* err);
 290
 291 extern const char kTemplate[];
 292 extern const char kTemplate_HelpShort[];
 293 extern const char kTemplate_Help[];
 294 Value RunTemplate(Scope* scope,
 295                   const FunctionCallNode* function,
 296                   const std::vector<Value>& args,
 297                   BlockNode* block,
 298                   Err* err);
 299
 300 extern const char kTool[];
 301 extern const char kTool_HelpShort[];
 302 extern const char kTool_Help[];
 303 Value RunTool(Scope* scope,
 304               const FunctionCallNode* function,
 305               const std::vector<Value>& args,
 306               BlockNode* block,
 307               Err* err);
 308
 309 extern const char kToolchain[];
 310 extern const char kToolchain_HelpShort[];
 311 extern const char kToolchain_Help[];
 312 Value RunToolchain(Scope* scope,
 313                    const FunctionCallNode* function,
 314                    const std::vector<Value>& args,
 315                    BlockNode* block,
 316                    Err* err);
 317
 318 extern const char kToolchainArgs[];
 319 extern const char kToolchainArgs_HelpShort[];
 320 extern const char kToolchainArgs_Help[];
 321 Value RunToolchainArgs(Scope* scope,
 322                        const FunctionCallNode* function,
 323                        const std::vector<Value>& args,
 324                        BlockNode* block,
 325                        Err* err);
 326
 327 extern const char kWriteFile[];
 328 extern const char kWriteFile_HelpShort[];
 329 extern const char kWriteFile_Help[];
 330 Value RunWriteFile(Scope* scope,
 331                    const FunctionCallNode* function,
 332                    const std::vector<Value>& args,
 333                    Err* err);
 334
 335 // -----------------------------------------------------------------------------
 336
 337 // One function record. Only one of the given runner types will be non-null
 338 // which indicates the type of function it is.
 339 struct FunctionInfo {
 340   FunctionInfo();
 341   FunctionInfo(SelfEvaluatingArgsFunction seaf,
 342                const char* in_help_short,
 343                const char* in_help,
 344                bool in_is_target);
 345   FunctionInfo(GenericBlockFunction gbf,
 346                const char* in_help_short,
 347                const char* in_help,
 348                bool in_is_target);
 349   FunctionInfo(ExecutedBlockFunction ebf,
 350                const char* in_help_short,
 351                const char* in_help,
 352                bool in_is_target);
 353   FunctionInfo(NoBlockFunction nbf,
 354                const char* in_help_short,
 355                const char* in_help,
 356                bool in_is_target);
 357
 358   SelfEvaluatingArgsFunction self_evaluating_args_runner;
 359   GenericBlockFunction generic_block_runner;
 360   ExecutedBlockFunction executed_block_runner;
 361   NoBlockFunction no_block_runner;
 362
 363   const char* help_short;
 364   const char* help;
 365
 366   bool is_target;
 367 };
 368
 369 typedef std::map<base::StringPiece, FunctionInfo> FunctionInfoMap;
 370
 371 // Returns the mapping of all built-in functions.
 372 const FunctionInfoMap& GetFunctions();
 373
 374 // Runs the given function.
 375 Value RunFunction(Scope* scope,
 376                   const FunctionCallNode* function,
 377                   const ListNode* args_list,
 378                   BlockNode* block,  // Optional.
 379                   Err* err);
 380
 381 }  // namespace functions
 382
 383 // Helper functions -----------------------------------------------------------
 384
 385 // Verifies that the current scope is not processing an import. If it is, it
 386 // will set the error, blame the given parse node for it, and return false.
 387 bool EnsureNotProcessingImport(const ParseNode* node,
 388                                const Scope* scope,
 389                                Err* err);
 390
 391 // Like EnsureNotProcessingImport but checks for running the build config.
 392 bool EnsureNotProcessingBuildConfig(const ParseNode* node,
 393                                     const Scope* scope,
 394                                     Err* err);
 395
 396 // Sets up the |block_scope| for executing a target (or something like it).
 397 // The |scope| is the containing scope. It should have been already set as the
 398 // parent for the |block_scope| when the |block_scope| was created.
 399 //
 400 // This will set up the target defaults and set the |target_name| variable in
 401 // the block scope to the current target name, which is assumed to be the first
 402 // argument to the function.
 403 //
 404 // On success, returns true. On failure, sets the error and returns false.
 405 bool FillTargetBlockScope(const Scope* scope,
 406                           const FunctionCallNode* function,
 407                           const std::string& target_type,
 408                           const BlockNode* block,
 409                           const std::vector<Value>& args,
 410                           Scope* block_scope,
 411                           Err* err);
 412
 413 // Sets the given error to a message explaining that the function call requires
 414 // a block.
 415 void FillNeedsBlockError(const FunctionCallNode* function, Err* err);
 416
 417 // Validates that the given function call has one string argument. This is
 418 // the most common function signature, so it saves space to have this helper.
 419 // Returns false and sets the error on failure.
 420 bool EnsureSingleStringArg(const FunctionCallNode* function,
 421                            const std::vector<Value>& args,
 422                            Err* err);
 423
 424 // Returns the name of the toolchain for the given scope.
 425 const Label& ToolchainLabelForScope(const Scope* scope);
 426
 427 // Generates a label for the given scope, using the current directory and
 428 // toolchain, and the given name.
 429 Label MakeLabelForScope(const Scope* scope,
 430                         const FunctionCallNode* function,
 431                         const std::string& name);
 432
 433 // Some tyesp of blocks can't be nested inside other ones. For such cases,
 434 // instantiate this object upon entering the block and Enter() will fail if
 435 // there is already another non-nestable block on the stack.
 436 class NonNestableBlock {
 437  public:
 438   enum Type {
 439     CONFIG,
 440     DECLARE_ARGS,
 441     TARGET,
 442     TEMPLATE,
 443     TOOLCHAIN,
 444   };
 445
 446   // type_description is a string that will be used in error messages
 447   // describing the type of the block, for example, "template" or "config".
 448   NonNestableBlock(Scope* scope,
 449                    const FunctionCallNode* function,
 450                    const char* type_description);
 451   ~NonNestableBlock();
 452
 453   bool Enter(Err* err);
 454
 455  private:
 456   // Used as a void* key for the Scope to track our property. The actual value
 457   // is never used.
 458   static const int kKey;
 459
 460   Scope* scope_;
 461   const FunctionCallNode* function_;
 462   const char* type_description_;
 463
 464   // Set to true when the key is added to the scope so we don't try to
 465   // delete nonexistant keys which will cause assertions.
 466   bool key_added_;
 467 };
 468
 469 #endif  // TOOLS_GN_FUNCTIONS_H_