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 kComponent[];
  84 extern const char kComponent_HelpShort[];
  85 extern const char kComponent_Help[];
  86 Value RunComponent(Scope* scope,
  87                    const FunctionCallNode* function,
  88                    const std::vector<Value>& args,
  89                    BlockNode* block,
  90                    Err* err);
  91
  92 extern const char kConfig[];
  93 extern const char kConfig_HelpShort[];
  94 extern const char kConfig_Help[];
  95 Value RunConfig(const FunctionCallNode* function,
  96                 const std::vector<Value>& args,
  97                 Scope* block_scope,
  98                 Err* err);
  99
 100 extern const char kCopy[];
 101 extern const char kCopy_HelpShort[];
 102 extern const char kCopy_Help[];
 103 Value RunCopy(const FunctionCallNode* function,
 104               const std::vector<Value>& args,
 105               Scope* block_scope,
 106               Err* err);
 107
 108 extern const char kDeclareArgs[];
 109 extern const char kDeclareArgs_HelpShort[];
 110 extern const char kDeclareArgs_Help[];
 111 Value RunDeclareArgs(Scope* scope,
 112                      const FunctionCallNode* function,
 113                      const std::vector<Value>& args,
 114                      BlockNode* block,
 115                      Err* err);
 116
 117 extern const char kDefined[];
 118 extern const char kDefined_HelpShort[];
 119 extern const char kDefined_Help[];
 120 Value RunDefined(Scope* scope,
 121                  const FunctionCallNode* function,
 122                  const ListNode* args_list,
 123                  Err* err);
 124
 125 extern const char kExecScript[];
 126 extern const char kExecScript_HelpShort[];
 127 extern const char kExecScript_Help[];
 128 Value RunExecScript(Scope* scope,
 129                     const FunctionCallNode* function,
 130                     const std::vector<Value>& args,
 131                     Err* err);
 132
 133 extern const char kExecutable[];
 134 extern const char kExecutable_HelpShort[];
 135 extern const char kExecutable_Help[];
 136 Value RunExecutable(Scope* scope,
 137                     const FunctionCallNode* function,
 138                     const std::vector<Value>& args,
 139                     BlockNode* block,
 140                     Err* err);
 141
 142 extern const char kForEach[];
 143 extern const char kForEach_HelpShort[];
 144 extern const char kForEach_Help[];
 145 Value RunForEach(Scope* scope,
 146                  const FunctionCallNode* function,
 147                  const ListNode* args_list,
 148                  Err* err);
 149
 150 extern const char kGetEnv[];
 151 extern const char kGetEnv_HelpShort[];
 152 extern const char kGetEnv_Help[];
 153 Value RunGetEnv(Scope* scope,
 154                 const FunctionCallNode* function,
 155                 const std::vector<Value>& args,
 156                 Err* err);
 157
 158 extern const char kGetLabelInfo[];
 159 extern const char kGetLabelInfo_HelpShort[];
 160 extern const char kGetLabelInfo_Help[];
 161 Value RunGetLabelInfo(Scope* scope,
 162                       const FunctionCallNode* function,
 163                       const std::vector<Value>& args,
 164                       Err* err);
 165
 166 extern const char kGetPathInfo[];
 167 extern const char kGetPathInfo_HelpShort[];
 168 extern const char kGetPathInfo_Help[];
 169 Value RunGetPathInfo(Scope* scope,
 170                      const FunctionCallNode* function,
 171                      const std::vector<Value>& args,
 172                      Err* err);
 173
 174 extern const char kGetTargetOutputs[];
 175 extern const char kGetTargetOutputs_HelpShort[];
 176 extern const char kGetTargetOutputs_Help[];
 177 Value RunGetTargetOutputs(Scope* scope,
 178                           const FunctionCallNode* function,
 179                           const std::vector<Value>& args,
 180                           Err* err);
 181
 182 extern const char kGroup[];
 183 extern const char kGroup_HelpShort[];
 184 extern const char kGroup_Help[];
 185 Value RunGroup(Scope* scope,
 186                const FunctionCallNode* function,
 187                const std::vector<Value>& args,
 188                BlockNode* block,
 189                Err* err);
 190
 191 extern const char kImport[];
 192 extern const char kImport_HelpShort[];
 193 extern const char kImport_Help[];
 194 Value RunImport(Scope* scope,
 195                 const FunctionCallNode* function,
 196                 const std::vector<Value>& args,
 197                 Err* err);
 198
 199 extern const char kPrint[];
 200 extern const char kPrint_HelpShort[];
 201 extern const char kPrint_Help[];
 202 Value RunPrint(Scope* scope,
 203                const FunctionCallNode* function,
 204                const std::vector<Value>& args,
 205                Err* err);
 206
 207 extern const char kProcessFileTemplate[];
 208 extern const char kProcessFileTemplate_HelpShort[];
 209 extern const char kProcessFileTemplate_Help[];
 210 Value RunProcessFileTemplate(Scope* scope,
 211                              const FunctionCallNode* function,
 212                              const std::vector<Value>& args,
 213                              Err* err);
 214
 215 extern const char kReadFile[];
 216 extern const char kReadFile_HelpShort[];
 217 extern const char kReadFile_Help[];
 218 Value RunReadFile(Scope* scope,
 219                   const FunctionCallNode* function,
 220                   const std::vector<Value>& args,
 221                   Err* err);
 222
 223 extern const char kRebasePath[];
 224 extern const char kRebasePath_HelpShort[];
 225 extern const char kRebasePath_Help[];
 226 Value RunRebasePath(Scope* scope,
 227                     const FunctionCallNode* function,
 228                     const std::vector<Value>& args,
 229                     Err* err);
 230
 231 extern const char kSetDefaults[];
 232 extern const char kSetDefaults_HelpShort[];
 233 extern const char kSetDefaults_Help[];
 234 Value RunSetDefaults(Scope* scope,
 235                      const FunctionCallNode* function,
 236                      const std::vector<Value>& args,
 237                      BlockNode* block,
 238                      Err* err);
 239
 240 extern const char kSetDefaultToolchain[];
 241 extern const char kSetDefaultToolchain_HelpShort[];
 242 extern const char kSetDefaultToolchain_Help[];
 243 Value RunSetDefaultToolchain(Scope* scope,
 244                              const FunctionCallNode* function,
 245                              const std::vector<Value>& args,
 246                              Err* err);
 247
 248 extern const char kSetSourcesAssignmentFilter[];
 249 extern const char kSetSourcesAssignmentFilter_HelpShort[];
 250 extern const char kSetSourcesAssignmentFilter_Help[];
 251 Value RunSetSourcesAssignmentFilter(Scope* scope,
 252                                     const FunctionCallNode* function,
 253                                     const std::vector<Value>& args,
 254                                     Err* err);
 255
 256 extern const char kSharedLibrary[];
 257 extern const char kSharedLibrary_HelpShort[];
 258 extern const char kSharedLibrary_Help[];
 259 Value RunSharedLibrary(Scope* scope,
 260                        const FunctionCallNode* function,
 261                        const std::vector<Value>& args,
 262                        BlockNode* block,
 263                        Err* err);
 264
 265 extern const char kSourceSet[];
 266 extern const char kSourceSet_HelpShort[];
 267 extern const char kSourceSet_Help[];
 268 Value RunSourceSet(Scope* scope,
 269                    const FunctionCallNode* function,
 270                    const std::vector<Value>& args,
 271                    BlockNode* block,
 272                    Err* err);
 273
 274 extern const char kStaticLibrary[];
 275 extern const char kStaticLibrary_HelpShort[];
 276 extern const char kStaticLibrary_Help[];
 277 Value RunStaticLibrary(Scope* scope,
 278                        const FunctionCallNode* function,
 279                        const std::vector<Value>& args,
 280                        BlockNode* block,
 281                        Err* err);
 282
 283 extern const char kTemplate[];
 284 extern const char kTemplate_HelpShort[];
 285 extern const char kTemplate_Help[];
 286 Value RunTemplate(Scope* scope,
 287                   const FunctionCallNode* function,
 288                   const std::vector<Value>& args,
 289                   BlockNode* block,
 290                   Err* err);
 291
 292 extern const char kTest[];
 293 extern const char kTest_HelpShort[];
 294 extern const char kTest_Help[];
 295 Value RunTest(Scope* scope,
 296               const FunctionCallNode* function,
 297               const std::vector<Value>& args,
 298               BlockNode* block,
 299               Err* err);
 300
 301 extern const char kTool[];
 302 extern const char kTool_HelpShort[];
 303 extern const char kTool_Help[];
 304 Value RunTool(Scope* scope,
 305               const FunctionCallNode* function,
 306               const std::vector<Value>& args,
 307               BlockNode* block,
 308               Err* err);
 309
 310 extern const char kToolchain[];
 311 extern const char kToolchain_HelpShort[];
 312 extern const char kToolchain_Help[];
 313 Value RunToolchain(Scope* scope,
 314                    const FunctionCallNode* function,
 315                    const std::vector<Value>& args,
 316                    BlockNode* block,
 317                    Err* err);
 318
 319 extern const char kToolchainArgs[];
 320 extern const char kToolchainArgs_HelpShort[];
 321 extern const char kToolchainArgs_Help[];
 322 Value RunToolchainArgs(Scope* scope,
 323                        const FunctionCallNode* function,
 324                        const std::vector<Value>& args,
 325                        BlockNode* block,
 326                        Err* err);
 327
 328 extern const char kWriteFile[];
 329 extern const char kWriteFile_HelpShort[];
 330 extern const char kWriteFile_Help[];
 331 Value RunWriteFile(Scope* scope,
 332                    const FunctionCallNode* function,
 333                    const std::vector<Value>& args,
 334                    Err* err);
 335
 336 // -----------------------------------------------------------------------------
 337
 338 // One function record. Only one of the given runner types will be non-null
 339 // which indicates the type of function it is.
 340 struct FunctionInfo {
 341   FunctionInfo();
 342   FunctionInfo(SelfEvaluatingArgsFunction seaf,
 343                const char* in_help_short,
 344                const char* in_help,
 345                bool in_is_target);
 346   FunctionInfo(GenericBlockFunction gbf,
 347                const char* in_help_short,
 348                const char* in_help,
 349                bool in_is_target);
 350   FunctionInfo(ExecutedBlockFunction ebf,
 351                const char* in_help_short,
 352                const char* in_help,
 353                bool in_is_target);
 354   FunctionInfo(NoBlockFunction nbf,
 355                const char* in_help_short,
 356                const char* in_help,
 357                bool in_is_target);
 358
 359   SelfEvaluatingArgsFunction self_evaluating_args_runner;
 360   GenericBlockFunction generic_block_runner;
 361   ExecutedBlockFunction executed_block_runner;
 362   NoBlockFunction no_block_runner;
 363
 364   const char* help_short;
 365   const char* help;
 366
 367   bool is_target;
 368 };
 369
 370 typedef std::map<base::StringPiece, FunctionInfo> FunctionInfoMap;
 371
 372 // Returns the mapping of all built-in functions.
 373 const FunctionInfoMap& GetFunctions();
 374
 375 // Runs the given function.
 376 Value RunFunction(Scope* scope,
 377                   const FunctionCallNode* function,
 378                   const ListNode* args_list,
 379                   BlockNode* block,  // Optional.
 380                   Err* err);
 381
 382 }  // namespace functions
 383
 384 // Helper functions -----------------------------------------------------------
 385
 386 // Verifies that the current scope is not processing an import. If it is, it
 387 // will set the error, blame the given parse node for it, and return false.
 388 bool EnsureNotProcessingImport(const ParseNode* node,
 389                                const Scope* scope,
 390                                Err* err);
 391
 392 // Like EnsureNotProcessingImport but checks for running the build config.
 393 bool EnsureNotProcessingBuildConfig(const ParseNode* node,
 394                                     const Scope* scope,
 395                                     Err* err);
 396
 397 // Sets up the |block_scope| for executing a target (or something like it).
 398 // The |scope| is the containing scope. It should have been already set as the
 399 // parent for the |block_scope| when the |block_scope| was created.
 400 //
 401 // This will set up the target defaults and set the |target_name| variable in
 402 // the block scope to the current target name, which is assumed to be the first
 403 // argument to the function.
 404 //
 405 // On success, returns true. On failure, sets the error and returns false.
 406 bool FillTargetBlockScope(const Scope* scope,
 407                           const FunctionCallNode* function,
 408                           const std::string& target_type,
 409                           const BlockNode* block,
 410                           const std::vector<Value>& args,
 411                           Scope* block_scope,
 412                           Err* err);
 413
 414 // Sets the given error to a message explaining that the function call requires
 415 // a block.
 416 void FillNeedsBlockError(const FunctionCallNode* function, Err* err);
 417
 418 // Validates that the given function call has one string argument. This is
 419 // the most common function signature, so it saves space to have this helper.
 420 // Returns false and sets the error on failure.
 421 bool EnsureSingleStringArg(const FunctionCallNode* function,
 422                            const std::vector<Value>& args,
 423                            Err* err);
 424
 425 // Returns the name of the toolchain for the given scope.
 426 const Label& ToolchainLabelForScope(const Scope* scope);
 427
 428 // Generates a label for the given scope, using the current directory and
 429 // toolchain, and the given name.
 430 Label MakeLabelForScope(const Scope* scope,
 431                         const FunctionCallNode* function,
 432                         const std::string& name);
 433
 434 #endif  // TOOLS_GN_FUNCTIONS_H_