tools/gn/function_toolchain.cc

   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 #include <algorithm>
   6 #include <limits>
   7
   8 #include "tools/gn/err.h"
   9 #include "tools/gn/functions.h"
  10 #include "tools/gn/parse_tree.h"
  11 #include "tools/gn/scheduler.h"
  12 #include "tools/gn/scope.h"
  13 #include "tools/gn/settings.h"
  14 #include "tools/gn/tool.h"
  15 #include "tools/gn/toolchain.h"
  16 #include "tools/gn/value_extractors.h"
  17 #include "tools/gn/variables.h"
  18
  19 namespace functions {
  20
  21 namespace {
  22
  23 // This is just a unique value to take the address of to use as the key for
  24 // the toolchain property on a scope.
  25 const int kToolchainPropertyKey = 0;
  26
  27 bool ReadBool(Scope* scope,
  28               const char* var,
  29               Tool* tool,
  30               void (Tool::*set)(bool),
  31               Err* err) {
  32   const Value* v = scope->GetValue(var, true);
  33   if (!v)
  34     return true;  // Not present is fine.
  35   if (!v->VerifyTypeIs(Value::BOOLEAN, err))
  36     return false;
  37
  38   (tool->*set)(v->boolean_value());
  39   return true;
  40 }
  41
  42 // Reads the given string from the scope (if present) and puts the result into
  43 // dest. If the value is not a string, sets the error and returns false.
  44 bool ReadString(Scope* scope,
  45                 const char* var,
  46                 Tool* tool,
  47                 void (Tool::*set)(const std::string&),
  48                 Err* err) {
  49   const Value* v = scope->GetValue(var, true);
  50   if (!v)
  51     return true;  // Not present is fine.
  52   if (!v->VerifyTypeIs(Value::STRING, err))
  53     return false;
  54
  55   (tool->*set)(v->string_value());
  56   return true;
  57 }
  58
  59 // Calls the given validate function on each type in the list. On failure,
  60 // sets the error, blame the value, and return false.
  61 bool ValidateSubstitutionList(const std::vector<SubstitutionType>& list,
  62                               bool (*validate)(SubstitutionType),
  63                               const Value* origin,
  64                               Err* err) {
  65   for (const auto& cur_type : list) {
  66     if (!validate(cur_type)) {
  67       *err = Err(*origin, "Pattern not valid here.",
  68           "You used the pattern " + std::string(kSubstitutionNames[cur_type]) +
  69           " which is not valid\nfor this variable.");
  70       return false;
  71     }
  72   }
  73   return true;
  74 }
  75
  76 bool ReadPattern(Scope* scope,
  77                  const char* name,
  78                  bool (*validate)(SubstitutionType),
  79                  Tool* tool,
  80                  void (Tool::*set)(const SubstitutionPattern&),
  81                  Err* err) {
  82   const Value* value = scope->GetValue(name, true);
  83   if (!value)
  84     return true;  // Not present is fine.
  85   if (!value->VerifyTypeIs(Value::STRING, err))
  86     return false;
  87
  88   SubstitutionPattern pattern;
  89   if (!pattern.Parse(*value, err))
  90     return false;
  91   if (!ValidateSubstitutionList(pattern.required_types(), validate, value, err))
  92     return false;
  93
  94   (tool->*set)(pattern);
  95   return true;
  96 }
  97
  98 bool ReadOutputExtension(Scope* scope, Tool* tool, Err* err) {
  99   const Value* value = scope->GetValue("default_output_extension", true);
 100   if (!value)
 101     return true;  // Not present is fine.
 102   if (!value->VerifyTypeIs(Value::STRING, err))
 103     return false;
 104
 105   if (value->string_value().empty())
 106     return true;  // Accept empty string.
 107
 108   if (value->string_value()[0] != '.') {
 109     *err = Err(*value, "default_output_extension must begin with a '.'");
 110     return false;
 111   }
 112
 113   tool->set_default_output_extension(value->string_value());
 114   return true;
 115 }
 116
 117 bool ReadPrecompiledHeaderType(Scope* scope, Tool* tool, Err* err) {
 118   const Value* value = scope->GetValue("precompiled_header_type", true);
 119   if (!value)
 120     return true;  // Not present is fine.
 121   if (!value->VerifyTypeIs(Value::STRING, err))
 122     return false;
 123
 124   if (value->string_value().empty())
 125     return true;  // Accept empty string, do nothing (default is "no PCH").
 126
 127   if (value->string_value() == "gcc") {
 128     tool->set_precompiled_header_type(Tool::PCH_GCC);
 129     return true;
 130   } else if (value->string_value() == "msvc") {
 131     tool->set_precompiled_header_type(Tool::PCH_MSVC);
 132     return true;
 133   }
 134   *err = Err(*value, "Invalid precompiled_header_type",
 135              "Must either be empty, \"gcc\", or \"msvc\".");
 136   return false;
 137 }
 138
 139 bool ReadDepsFormat(Scope* scope, Tool* tool, Err* err) {
 140   const Value* value = scope->GetValue("depsformat", true);
 141   if (!value)
 142     return true;  // Not present is fine.
 143   if (!value->VerifyTypeIs(Value::STRING, err))
 144     return false;
 145
 146   if (value->string_value() == "gcc") {
 147     tool->set_depsformat(Tool::DEPS_GCC);
 148   } else if (value->string_value() == "msvc") {
 149     tool->set_depsformat(Tool::DEPS_MSVC);
 150   } else {
 151     *err = Err(*value, "Deps format must be \"gcc\" or \"msvc\".");
 152     return false;
 153   }
 154   return true;
 155 }
 156
 157 bool ReadOutputs(Scope* scope,
 158                  const FunctionCallNode* tool_function,
 159                  bool (*validate)(SubstitutionType),
 160                  Tool* tool,
 161                  Err* err) {
 162   const Value* value = scope->GetValue("outputs", true);
 163   if (!value) {
 164     *err = Err(tool_function, "\"outputs\" must be specified for this tool.");
 165     return false;
 166   }
 167
 168   SubstitutionList list;
 169   if (!list.Parse(*value, err))
 170     return false;
 171
 172   // Validate the right kinds of patterns are used.
 173   if (!ValidateSubstitutionList(list.required_types(), validate, value, err))
 174     return false;
 175
 176   // There should always be at least one output.
 177   if (list.list().empty()) {
 178     *err = Err(*value, "Outputs list is empty.", "I need some outputs.");
 179     return false;
 180   }
 181
 182   tool->set_outputs(list);
 183   return true;
 184 }
 185
 186 bool IsCompilerTool(Toolchain::ToolType type) {
 187   return type == Toolchain::TYPE_CC ||
 188          type == Toolchain::TYPE_CXX ||
 189          type == Toolchain::TYPE_OBJC ||
 190          type == Toolchain::TYPE_OBJCXX ||
 191          type == Toolchain::TYPE_RC ||
 192          type == Toolchain::TYPE_ASM;
 193 }
 194
 195 bool IsLinkerTool(Toolchain::ToolType type) {
 196   return type == Toolchain::TYPE_ALINK ||
 197          type == Toolchain::TYPE_SOLINK ||
 198          type == Toolchain::TYPE_LINK;
 199 }
 200
 201 bool IsPatternInOutputList(const SubstitutionList& output_list,
 202                            const SubstitutionPattern& pattern) {
 203   for (const auto& cur : output_list.list()) {
 204     if (pattern.ranges().size() == cur.ranges().size() &&
 205         std::equal(pattern.ranges().begin(), pattern.ranges().end(),
 206                    cur.ranges().begin()))
 207       return true;
 208   }
 209   return false;
 210 }
 211
 212 }  // namespace
 213
 214 // toolchain -------------------------------------------------------------------
 215
 216 const char kToolchain[] = "toolchain";
 217 const char kToolchain_HelpShort[] =
 218     "toolchain: Defines a toolchain.";
 219 const char kToolchain_Help[] =
 220     "toolchain: Defines a toolchain.\n"
 221     "\n"
 222     "  A toolchain is a set of commands and build flags used to compile the\n"
 223     "  source code. You can have more than one toolchain in use at once in\n"
 224     "  a build.\n"
 225     "\n"
 226     "Functions and variables\n"
 227     "\n"
 228     "  tool()\n"
 229     "    The tool() function call specifies the commands commands to run for\n"
 230     "    a given step. See \"gn help tool\".\n"
 231     "\n"
 232     "  toolchain_args()\n"
 233     "    List of arguments to pass to the toolchain when invoking this\n"
 234     "    toolchain. This applies only to non-default toolchains. See\n"
 235     "    \"gn help toolchain_args\" for more.\n"
 236     "\n"
 237     "  deps\n"
 238     "    Dependencies of this toolchain. These dependencies will be resolved\n"
 239     "    before any target in the toolchain is compiled. To avoid circular\n"
 240     "    dependencies these must be targets defined in another toolchain.\n"
 241     "\n"
 242     "    This is expressed as a list of targets, and generally these targets\n"
 243     "    will always specify a toolchain:\n"
 244     "      deps = [ \"//foo/bar:baz(//build/toolchain:bootstrap)\" ]\n"
 245     "\n"
 246     "    This concept is somewhat inefficient to express in Ninja (it\n"
 247     "    requires a lot of duplicate of rules) so should only be used when\n"
 248     "    absolutely necessary.\n"
 249     "\n"
 250     "  concurrent_links\n"
 251     "    In integer expressing the number of links that Ninja will perform in\n"
 252     "    parallel. GN will create a pool for shared library and executable\n"
 253     "    link steps with this many processes. Since linking is memory- and\n"
 254     "    I/O-intensive, projects with many large targets may want to limit\n"
 255     "    the number of parallel steps to avoid overloading the computer.\n"
 256     "    Since creating static libraries is generally not as intensive\n"
 257     "    there is no limit to \"alink\" steps.\n"
 258     "\n"
 259     "    Defaults to 0 which Ninja interprets as \"no limit\".\n"
 260     "\n"
 261     "    The value used will be the one from the default toolchain of the\n"
 262     "    current build.\n"
 263     "\n"
 264     "Invoking targets in toolchains:\n"
 265     "\n"
 266     "  By default, when a target depends on another, there is an implicit\n"
 267     "  toolchain label that is inherited, so the dependee has the same one\n"
 268     "  as the dependent.\n"
 269     "\n"
 270     "  You can override this and refer to any other toolchain by explicitly\n"
 271     "  labeling the toolchain to use. For example:\n"
 272     "    data_deps = [ \"//plugins:mine(//toolchains:plugin_toolchain)\" ]\n"
 273     "  The string \"//build/toolchains:plugin_toolchain\" is a label that\n"
 274     "  identifies the toolchain declaration for compiling the sources.\n"
 275     "\n"
 276     "  To load a file in an alternate toolchain, GN does the following:\n"
 277     "\n"
 278     "   1. Loads the file with the toolchain definition in it (as determined\n"
 279     "      by the toolchain label).\n"
 280     "   2. Re-runs the master build configuration file, applying the\n"
 281     "      arguments specified by the toolchain_args section of the toolchain\n"
 282     "      definition (see \"gn help toolchain_args\").\n"
 283     "   3. Loads the destination build file in the context of the\n"
 284     "      configuration file in the previous step.\n"
 285     "\n"
 286     "Example:\n"
 287     "  toolchain(\"plugin_toolchain\") {\n"
 288     "    concurrent_links = 8\n"
 289     "\n"
 290     "    tool(\"cc\") {\n"
 291     "      command = \"gcc {{source}}\"\n"
 292     "      ...\n"
 293     "    }\n"
 294     "\n"
 295     "    toolchain_args() {\n"
 296     "      is_plugin = true\n"
 297     "      is_32bit = true\n"
 298     "      is_64bit = false\n"
 299     "    }\n"
 300     "  }\n";
 301
 302 Value RunToolchain(Scope* scope,
 303                    const FunctionCallNode* function,
 304                    const std::vector<Value>& args,
 305                    BlockNode* block,
 306                    Err* err) {
 307   NonNestableBlock non_nestable(scope, function, "toolchain");
 308   if (!non_nestable.Enter(err))
 309     return Value();
 310
 311   if (!EnsureNotProcessingImport(function, scope, err) ||
 312       !EnsureNotProcessingBuildConfig(function, scope, err))
 313     return Value();
 314
 315   // Note that we don't want to use MakeLabelForScope since that will include
 316   // the toolchain name in the label, and toolchain labels don't themselves
 317   // have toolchain names.
 318   const SourceDir& input_dir = scope->GetSourceDir();
 319   Label label(input_dir, args[0].string_value());
 320   if (g_scheduler->verbose_logging())
 321     g_scheduler->Log("Defining toolchain", label.GetUserVisibleName(false));
 322
 323   // This object will actually be copied into the one owned by the toolchain
 324   // manager, but that has to be done in the lock.
 325   scoped_ptr<Toolchain> toolchain(new Toolchain(scope->settings(), label));
 326   toolchain->set_defined_from(function);
 327   toolchain->visibility().SetPublic();
 328
 329   Scope block_scope(scope);
 330   block_scope.SetProperty(&kToolchainPropertyKey, toolchain.get());
 331   block->Execute(&block_scope, err);
 332   block_scope.SetProperty(&kToolchainPropertyKey, nullptr);
 333   if (err->has_error())
 334     return Value();
 335
 336   // Read deps (if any).
 337   const Value* deps_value = block_scope.GetValue(variables::kDeps, true);
 338   if (deps_value) {
 339     ExtractListOfLabels(
 340         *deps_value, block_scope.GetSourceDir(),
 341         ToolchainLabelForScope(&block_scope), &toolchain->deps(), err);
 342     if (err->has_error())
 343       return Value();
 344   }
 345
 346   // Read concurrent_links (if any).
 347   const Value* concurrent_links_value =
 348       block_scope.GetValue("concurrent_links", true);
 349   if (concurrent_links_value) {
 350     if (!concurrent_links_value->VerifyTypeIs(Value::INTEGER, err))
 351       return Value();
 352     if (concurrent_links_value->int_value() < 0 ||
 353         concurrent_links_value->int_value() > std::numeric_limits<int>::max()) {
 354       *err = Err(*concurrent_links_value, "Value out of range.");
 355       return Value();
 356     }
 357     toolchain->set_concurrent_links(
 358         static_cast<int>(concurrent_links_value->int_value()));
 359   }
 360
 361   if (!block_scope.CheckForUnusedVars(err))
 362     return Value();
 363
 364   // Save this toolchain.
 365   toolchain->ToolchainSetupComplete();
 366   Scope::ItemVector* collector = scope->GetItemCollector();
 367   if (!collector) {
 368     *err = Err(function, "Can't define a toolchain in this context.");
 369     return Value();
 370   }
 371   collector->push_back(toolchain.release());
 372   return Value();
 373 }
 374
 375 // tool ------------------------------------------------------------------------
 376
 377 const char kTool[] = "tool";
 378 const char kTool_HelpShort[] =
 379     "tool: Specify arguments to a toolchain tool.";
 380 const char kTool_Help[] =
 381     "tool: Specify arguments to a toolchain tool.\n"
 382     "\n"
 383     "Usage:\n"
 384     "\n"
 385     "  tool(<tool type>) {\n"
 386     "    <tool variables...>\n"
 387     "  }\n"
 388     "\n"
 389     "Tool types\n"
 390     "\n"
 391     "    Compiler tools:\n"
 392     "      \"cc\": C compiler\n"
 393     "      \"cxx\": C++ compiler\n"
 394     "      \"objc\": Objective C compiler\n"
 395     "      \"objcxx\": Objective C++ compiler\n"
 396     "      \"rc\": Resource compiler (Windows .rc files)\n"
 397     "      \"asm\": Assembler\n"
 398     "\n"
 399     "    Linker tools:\n"
 400     "      \"alink\": Linker for static libraries (archives)\n"
 401     "      \"solink\": Linker for shared libraries\n"
 402     "      \"link\": Linker for executables\n"
 403     "\n"
 404     "    Other tools:\n"
 405     "      \"stamp\": Tool for creating stamp files\n"
 406     "      \"copy\": Tool to copy files.\n"
 407     "\n"
 408     "Tool variables\n"
 409     "\n"
 410     "    command  [string with substitutions]\n"
 411     "        Valid for: all tools (required)\n"
 412     "\n"
 413     "        The command to run.\n"
 414     "\n"
 415     "    default_output_extension  [string]\n"
 416     "        Valid for: linker tools\n"
 417     "\n"
 418     "        Extension for the main output of a linkable tool. It includes\n"
 419     "        the leading dot. This will be the default value for the\n"
 420     "        {{output_extension}} expansion (discussed below) but will be\n"
 421     "        overridden by by the \"output extension\" variable in a target,\n"
 422     "        if one is specified. Empty string means no extension.\n"
 423     "\n"
 424     "        GN doesn't actually do anything with this extension other than\n"
 425     "        pass it along, potentially with target-specific overrides. One\n"
 426     "        would typically use the {{output_extension}} value in the\n"
 427     "        \"outputs\" to read this value.\n"
 428     "\n"
 429     "        Example: default_output_extension = \".exe\"\n"
 430     "\n"
 431     "    depfile  [string]\n"
 432     "        Valid for: compiler tools (optional)\n"
 433     "\n"
 434     "        If the tool can write \".d\" files, this specifies the name of\n"
 435     "        the resulting file. These files are used to list header file\n"
 436     "        dependencies (or other implicit input dependencies) that are\n"
 437     "        discovered at build time. See also \"depsformat\".\n"
 438     "\n"
 439     "        Example: depfile = \"{{output}}.d\"\n"
 440     "\n"
 441     "    depsformat  [string]\n"
 442     "        Valid for: compiler tools (when depfile is specified)\n"
 443     "\n"
 444     "        Format for the deps outputs. This is either \"gcc\" or \"msvc\".\n"
 445     "        See the ninja documentation for \"deps\" for more information.\n"
 446     "\n"
 447     "        Example: depsformat = \"gcc\"\n"
 448     "\n"
 449     "    description  [string with substitutions, optional]\n"
 450     "        Valid for: all tools\n"
 451     "\n"
 452     "        What to print when the command is run.\n"
 453     "\n"
 454     "        Example: description = \"Compiling {{source}}\"\n"
 455     "\n"
 456     "    lib_switch  [string, optional, link tools only]\n"
 457     "    lib_dir_switch  [string, optional, link tools only]\n"
 458     "        Valid for: Linker tools except \"alink\"\n"
 459     "\n"
 460     "        These strings will be prepended to the libraries and library\n"
 461     "        search directories, respectively, because linkers differ on how\n"
 462     "        specify them. If you specified:\n"
 463     "          lib_switch = \"-l\"\n"
 464     "          lib_dir_switch = \"-L\"\n"
 465     "        then the \"{{libs}}\" expansion for [ \"freetype\", \"expat\"]\n"
 466     "        would be \"-lfreetype -lexpat\".\n"
 467     "\n"
 468     "    outputs  [list of strings with substitutions]\n"
 469     "        Valid for: Linker and compiler tools (required)\n"
 470     "\n"
 471     "        An array of names for the output files the tool produces. These\n"
 472     "        are relative to the build output directory. There must always be\n"
 473     "        at least one output file. There can be more than one output (a\n"
 474     "        linker might produce a library and an import library, for\n"
 475     "        example).\n"
 476     "\n"
 477     "        This array just declares to GN what files the tool will\n"
 478     "        produce. It is your responsibility to specify the tool command\n"
 479     "        that actually produces these files.\n"
 480     "\n"
 481     "        If you specify more than one output for shared library links,\n"
 482     "        you should consider setting link_output and depend_output.\n"
 483     "        Otherwise, the first entry in the outputs list should always be\n"
 484     "        the main output which will be linked to.\n"
 485     "\n"
 486     "        Example for a compiler tool that produces .obj files:\n"
 487     "          outputs = [\n"
 488     "            \"{{source_out_dir}}/{{source_name_part}}.obj\"\n"
 489     "          ]\n"
 490     "\n"
 491     "        Example for a linker tool that produces a .dll and a .lib. The\n"
 492     "        use of {{output_extension}} rather than hardcoding \".dll\"\n"
 493     "        allows the extension of the library to be overridden on a\n"
 494     "        target-by-target basis, but in this example, it always\n"
 495     "        produces a \".lib\" import library:\n"
 496     "          outputs = [\n"
 497     "            \"{{root_out_dir}}/{{target_output_name}}"
 498                      "{{output_extension}}\",\n"
 499     "            \"{{root_out_dir}}/{{target_output_name}}.lib\",\n"
 500     "          ]\n"
 501     "\n"
 502     "    link_output  [string with substitutions]\n"
 503     "    depend_output  [string with substitutions]\n"
 504     "        Valid for: \"solink\" only (optional)\n"
 505     "\n"
 506     "        These two files specify whch of the outputs from the solink\n"
 507     "        tool should be used for linking and dependency tracking. These\n"
 508     "        should match entries in the \"outputs\". If unspecified, the\n"
 509     "        first item in the \"outputs\" array will be used for both. See\n"
 510     "        \"Separate linking and dependencies for shared libraries\"\n"
 511     "        below for more.\n"
 512     "\n"
 513     "        On Windows, where the tools produce a .dll shared library and\n"
 514     "        a .lib import library, you will want both of these to be the\n"
 515     "        import library. On Linux, if you're not doing the separate\n"
 516     "        linking/dependency optimization, both of these should be the\n"
 517     "        .so output.\n"
 518     "\n"
 519     "    output_prefix  [string]\n"
 520     "        Valid for: Linker tools (optional)\n"
 521     "\n"
 522     "        Prefix to use for the output name. Defaults to empty. This\n"
 523     "        prefix will be prepended to the name of the target (or the\n"
 524     "        output_name if one is manually specified for it) if the prefix\n"
 525     "        is not already there. The result will show up in the\n"
 526     "        {{output_name}} substitution pattern.\n"
 527     "\n"
 528     "        This is typically used to prepend \"lib\" to libraries on\n"
 529     "        Posix systems:\n"
 530     "          output_prefix = \"lib\"\n"
 531     "\n"
 532     "    precompiled_header_type  [string]\n"
 533     "        Valid for: \"cc\", \"cxx\", \"objc\", \"objcxx\"\n"
 534     "\n"
 535     "        Type of precompiled headers. If undefined or the empty string,\n"
 536     "        precompiled headers will not be used for this tool. Otherwise\n"
 537     "        use \"gcc\" or \"msvc\".\n"
 538     "\n"
 539     "        For precompiled headers to be used for a given target, the\n"
 540     "        target (or a config applied to it) must also specify a\n"
 541     "        \"precompiled_header\" and, for \"msvc\"-style headers, a\n"
 542     "        \"precompiled_source\" value. If the type is \"gcc\", then both\n"
 543     "        \"precompiled_header\" and \"precompiled_source\" must resolve\n"
 544     "        to the same file, despite the different formats required for each."
 545     "\n"
 546     "        See \"gn help precompiled_header\" for more.\n"
 547     "\n"
 548     "    restat  [boolean]\n"
 549     "        Valid for: all tools (optional, defaults to false)\n"
 550     "\n"
 551     "        Requests that Ninja check the file timestamp after this tool has\n"
 552     "        run to determine if anything changed. Set this if your tool has\n"
 553     "        the ability to skip writing output if the output file has not\n"
 554     "        changed.\n"
 555     "\n"
 556     "        Normally, Ninja will assume that when a tool runs the output\n"
 557     "        be new and downstream dependents must be rebuild. When this is\n"
 558     "        set to trye, Ninja can skip rebuilding downstream dependents for\n"
 559     "        input changes that don't actually affect the output.\n"
 560     "\n"
 561     "        Example:\n"
 562     "          restat = true\n"
 563     "\n"
 564     "    rspfile  [string with substitutions]\n"
 565     "        Valid for: all tools (optional)\n"
 566     "\n"
 567     "        Name of the response file. If empty, no response file will be\n"
 568     "        used. See \"rspfile_content\".\n"
 569     "\n"
 570     "    rspfile_content  [string with substitutions]\n"
 571     "        Valid for: all tools (required when \"rspfile\" is specified)\n"
 572     "\n"
 573     "        The contents to be written to the response file. This may\n"
 574     "        include all or part of the command to send to the tool which\n"
 575     "        allows you to get around OS command-line length limits.\n"
 576     "\n"
 577     "        This example adds the inputs and libraries to a response file,\n"
 578     "        but passes the linker flags directly on the command line:\n"
 579     "          tool(\"link\") {\n"
 580     "            command = \"link -o {{output}} {{ldflags}} @{{output}}.rsp\"\n"
 581     "            rspfile = \"{{output}}.rsp\"\n"
 582     "            rspfile_content = \"{{inputs}} {{solibs}} {{libs}}\"\n"
 583     "          }\n"
 584     "\n"
 585     "Expansions for tool variables\n"
 586     "\n"
 587     "  All paths are relative to the root build directory, which is the\n"
 588     "  current directory for running all tools. These expansions are\n"
 589     "  available to all tools:\n"
 590     "\n"
 591     "    {{label}}\n"
 592     "        The label of the current target. This is typically used in the\n"
 593     "        \"description\" field for link tools. The toolchain will be\n"
 594     "        omitted from the label for targets in the default toolchain, and\n"
 595     "        will be included for targets in other toolchains.\n"
 596     "\n"
 597     "    {{output}}\n"
 598     "        The relative path and name of the output(s) of the current\n"
 599     "        build step. If there is more than one output, this will expand\n"
 600     "        to a list of all of them.\n"
 601     "        Example: \"out/base/my_file.o\"\n"
 602     "\n"
 603     "    {{target_gen_dir}}\n"
 604     "    {{target_out_dir}}\n"
 605     "        The directory of the generated file and output directories,\n"
 606     "        respectively, for the current target. There is no trailing\n"
 607     "        slash.\n"
 608     "        Example: \"out/base/test\"\n"
 609     "\n"
 610     "    {{target_output_name}}\n"
 611     "        The short name of the current target with no path information,\n"
 612     "        or the value of the \"output_name\" variable if one is specified\n"
 613     "        in the target. This will include the \"output_prefix\" if any.\n"
 614     "        Example: \"libfoo\" for the target named \"foo\" and an\n"
 615     "        output prefix for the linker tool of \"lib\".\n"
 616     "\n"
 617     "  Compiler tools have the notion of a single input and a single output,\n"
 618     "  along with a set of compiler-specific flags. The following expansions\n"
 619     "  are available:\n"
 620     "\n"
 621     "    {{cflags}}\n"
 622     "    {{cflags_c}}\n"
 623     "    {{cflags_cc}}\n"
 624     "    {{cflags_objc}}\n"
 625     "    {{cflags_objcc}}\n"
 626     "    {{defines}}\n"
 627     "    {{include_dirs}}\n"
 628     "        Strings correspond that to the processed flags/defines/include\n"
 629     "        directories specified for the target.\n"
 630     "        Example: \"--enable-foo --enable-bar\"\n"
 631     "\n"
 632     "        Defines will be prefixed by \"-D\" and include directories will\n"
 633     "        be prefixed by \"-I\" (these work with Posix tools as well as\n"
 634     "        Microsoft ones).\n"
 635     "\n"
 636     "    {{source}}\n"
 637     "        The relative path and name of the current input file.\n"
 638     "        Example: \"../../base/my_file.cc\"\n"
 639     "\n"
 640     "    {{source_file_part}}\n"
 641     "        The file part of the source including the extension (with no\n"
 642     "        directory information).\n"
 643     "        Example: \"foo.cc\"\n"
 644     "\n"
 645     "    {{source_name_part}}\n"
 646     "        The filename part of the source file with no directory or\n"
 647     "        extension.\n"
 648     "        Example: \"foo\"\n"
 649     "\n"
 650     "    {{source_gen_dir}}\n"
 651     "    {{source_out_dir}}\n"
 652     "        The directory in the generated file and output directories,\n"
 653     "        respectively, for the current input file. If the source file\n"
 654     "        is in the same directory as the target is declared in, they will\n"
 655     "        will be the same as the \"target\" versions above.\n"
 656     "        Example: \"gen/base/test\"\n"
 657     "\n"
 658     "  Linker tools have multiple inputs and (potentially) multiple outputs\n"
 659     "  The following expansions are available:\n"
 660     "\n"
 661     "    {{inputs}}\n"
 662     "    {{inputs_newline}}\n"
 663     "        Expands to the inputs to the link step. This will be a list of\n"
 664     "        object files and static libraries.\n"
 665     "        Example: \"obj/foo.o obj/bar.o obj/somelibrary.a\"\n"
 666     "\n"
 667     "        The \"_newline\" version will separate the input files with\n"
 668     "        newlines instead of spaces. This is useful in response files:\n"
 669     "        some linkers can take a \"-filelist\" flag which expects newline\n"
 670     "        separated files, and some Microsoft tools have a fixed-sized\n"
 671     "        buffer for parsing each line of a response file.\n"
 672     "\n"
 673     "    {{ldflags}}\n"
 674     "        Expands to the processed set of ldflags and library search paths\n"
 675     "        specified for the target.\n"
 676     "        Example: \"-m64 -fPIC -pthread -L/usr/local/mylib\"\n"
 677     "\n"
 678     "    {{libs}}\n"
 679     "        Expands to the list of system libraries to link to. Each will\n"
 680     "        be prefixed by the \"lib_prefix\".\n"
 681     "\n"
 682     "        As a special case to support Mac, libraries with names ending in\n"
 683     "        \".framework\" will be added to the {{libs}} with \"-framework\"\n"
 684     "        preceeding it, and the lib prefix will be ignored.\n"
 685     "\n"
 686     "        Example: \"-lfoo -lbar\"\n"
 687     "\n"
 688     "    {{output_extension}}\n"
 689     "        The value of the \"output_extension\" variable in the target,\n"
 690     "        or the value of the \"default_output_extension\" value in the\n"
 691     "        tool if the target does not specify an output extension.\n"
 692     "        Example: \".so\"\n"
 693     "\n"
 694     "    {{solibs}}\n"
 695     "        Extra libraries from shared library dependencide not specified\n"
 696     "        in the {{inputs}}. This is the list of link_output files from\n"
 697     "        shared libraries (if the solink tool specifies a \"link_output\"\n"
 698     "        variable separate from the \"depend_output\").\n"
 699     "\n"
 700     "        These should generally be treated the same as libs by your tool.\n"
 701     "        Example: \"libfoo.so libbar.so\"\n"
 702     "\n"
 703     "  The copy tool allows the common compiler/linker substitutions, plus\n"
 704     "  {{source}} which is the source of the copy. The stamp tool allows\n"
 705     "  only the common tool substitutions.\n"
 706     "\n"
 707     "Separate linking and dependencies for shared libraries\n"
 708     "\n"
 709     "  Shared libraries are special in that not all changes to them require\n"
 710     "  that dependent targets be re-linked. If the shared library is changed\n"
 711     "  but no imports or exports are different, dependent code needn't be\n"
 712     "  relinked, which can speed up the build.\n"
 713     "\n"
 714     "  If your link step can output a list of exports from a shared library\n"
 715     "  and writes the file only if the new one is different, the timestamp of\n"
 716     "  this file can be used for triggering re-links, while the actual shared\n"
 717     "  library would be used for linking.\n"
 718     "\n"
 719     "  You will need to specify\n"
 720     "    restat = true\n"
 721     "  in the linker tool to make this work, so Ninja will detect if the\n"
 722     "  timestamp of the dependency file has changed after linking (otherwise\n"
 723     "  it will always assume that running a command updates the output):\n"
 724     "\n"
 725     "    tool(\"solink\") {\n"
 726     "      command = \"...\"\n"
 727     "      outputs = [\n"
 728     "        \"{{root_out_dir}}/{{target_output_name}}{{output_extension}}\",\n"
 729     "        \"{{root_out_dir}}/{{target_output_name}}"
 730                  "{{output_extension}}.TOC\",\n"
 731     "      ]\n"
 732     "      link_output =\n"
 733     "        \"{{root_out_dir}}/{{target_output_name}}{{output_extension}}\"\n"
 734     "      depend_output =\n"
 735     "        \"{{root_out_dir}}/{{target_output_name}}"
 736                  "{{output_extension}}.TOC\"\n"
 737     "      restat = true\n"
 738     "    }\n"
 739     "\n"
 740     "Example\n"
 741     "\n"
 742     "  toolchain(\"my_toolchain\") {\n"
 743     "    # Put these at the top to apply to all tools below.\n"
 744     "    lib_prefix = \"-l\"\n"
 745     "    lib_dir_prefix = \"-L\"\n"
 746     "\n"
 747     "    tool(\"cc\") {\n"
 748     "      command = \"gcc {{source}} -o {{output}}\"\n"
 749     "      outputs = [ \"{{source_out_dir}}/{{source_name_part}}.o\" ]\n"
 750     "      description = \"GCC {{source}}\"\n"
 751     "    }\n"
 752     "    tool(\"cxx\") {\n"
 753     "      command = \"g++ {{source}} -o {{output}}\"\n"
 754     "      outputs = [ \"{{source_out_dir}}/{{source_name_part}}.o\" ]\n"
 755     "      description = \"G++ {{source}}\"\n"
 756     "    }\n"
 757     "  }\n";
 758
 759 Value RunTool(Scope* scope,
 760               const FunctionCallNode* function,
 761               const std::vector<Value>& args,
 762               BlockNode* block,
 763               Err* err) {
 764   // Find the toolchain definition we're executing inside of. The toolchain
 765   // function will set a property pointing to it that we'll pick up.
 766   Toolchain* toolchain = reinterpret_cast<Toolchain*>(
 767       scope->GetProperty(&kToolchainPropertyKey, nullptr));
 768   if (!toolchain) {
 769     *err = Err(function->function(), "tool() called outside of toolchain().",
 770         "The tool() function can only be used inside a toolchain() "
 771         "definition.");
 772     return Value();
 773   }
 774
 775   if (!EnsureSingleStringArg(function, args, err))
 776     return Value();
 777   const std::string& tool_name = args[0].string_value();
 778   Toolchain::ToolType tool_type = Toolchain::ToolNameToType(tool_name);
 779   if (tool_type == Toolchain::TYPE_NONE) {
 780     *err = Err(args[0], "Unknown tool type");
 781     return Value();
 782   }
 783
 784   // Run the tool block.
 785   Scope block_scope(scope);
 786   block->Execute(&block_scope, err);
 787   if (err->has_error())
 788     return Value();
 789
 790   // Figure out which validator to use for the substitution pattern for this
 791   // tool type. There are different validators for the "outputs" than for the
 792   // rest of the strings.
 793   bool (*subst_validator)(SubstitutionType) = nullptr;
 794   bool (*subst_output_validator)(SubstitutionType) = nullptr;
 795   if (IsCompilerTool(tool_type)) {
 796     subst_validator = &IsValidCompilerSubstitution;
 797     subst_output_validator = &IsValidCompilerOutputsSubstitution;
 798   } else if (IsLinkerTool(tool_type)) {
 799     subst_validator = &IsValidLinkerSubstitution;
 800     subst_output_validator = &IsValidLinkerOutputsSubstitution;
 801   } else if (tool_type == Toolchain::TYPE_COPY) {
 802     subst_validator = &IsValidCopySubstitution;
 803     subst_output_validator = &IsValidCopySubstitution;
 804   } else {
 805     subst_validator = &IsValidToolSubstutition;
 806     subst_output_validator = &IsValidToolSubstutition;
 807   }
 808
 809   scoped_ptr<Tool> tool(new Tool);
 810
 811   if (!ReadPattern(&block_scope, "command", subst_validator, tool.get(),
 812                    &Tool::set_command, err) ||
 813       !ReadOutputExtension(&block_scope, tool.get(), err) ||
 814       !ReadPattern(&block_scope, "depfile", subst_validator, tool.get(),
 815                    &Tool::set_depfile, err) ||
 816       !ReadDepsFormat(&block_scope, tool.get(), err) ||
 817       !ReadPattern(&block_scope, "description", subst_validator, tool.get(),
 818                    &Tool::set_description, err) ||
 819       !ReadString(&block_scope, "lib_switch", tool.get(),
 820                   &Tool::set_lib_switch, err) ||
 821       !ReadString(&block_scope, "lib_dir_switch", tool.get(),
 822                   &Tool::set_lib_dir_switch, err) ||
 823       !ReadPattern(&block_scope, "link_output", subst_validator, tool.get(),
 824                    &Tool::set_link_output, err) ||
 825       !ReadPattern(&block_scope, "depend_output", subst_validator, tool.get(),
 826                    &Tool::set_depend_output, err) ||
 827       !ReadString(&block_scope, "output_prefix", tool.get(),
 828                   &Tool::set_output_prefix, err) ||
 829       !ReadPrecompiledHeaderType(&block_scope, tool.get(), err) ||
 830       !ReadBool(&block_scope, "restat", tool.get(), &Tool::set_restat, err) ||
 831       !ReadPattern(&block_scope, "rspfile", subst_validator, tool.get(),
 832                    &Tool::set_rspfile, err) ||
 833       !ReadPattern(&block_scope, "rspfile_content", subst_validator, tool.get(),
 834                    &Tool::set_rspfile_content, err)) {
 835     return Value();
 836   }
 837
 838   if (tool_type != Toolchain::TYPE_COPY && tool_type != Toolchain::TYPE_STAMP) {
 839     // All tools except the copy and stamp tools should have outputs. The copy
 840     // and stamp tool's outputs are generated internally.
 841     if (!ReadOutputs(&block_scope, function, subst_output_validator,
 842                      tool.get(), err))
 843       return Value();
 844   }
 845
 846   // Validate that the link_output and depend_output refer to items in the
 847   // outputs and aren't defined for irrelevant tool types.
 848   if (!tool->link_output().empty()) {
 849     if (tool_type != Toolchain::TYPE_SOLINK) {
 850       *err = Err(function, "This tool specifies a link_output.",
 851           "This is only valid for solink tools.");
 852       return Value();
 853     }
 854     if (!IsPatternInOutputList(tool->outputs(), tool->link_output())) {
 855       *err = Err(function, "This tool's link_output is bad.",
 856                  "It must match one of the outputs.");
 857       return Value();
 858     }
 859   }
 860   if (!tool->depend_output().empty()) {
 861     if (tool_type != Toolchain::TYPE_SOLINK) {
 862       *err = Err(function, "This tool specifies a depend_output.",
 863           "This is only valid for solink tools.");
 864       return Value();
 865     }
 866     if (!IsPatternInOutputList(tool->outputs(), tool->depend_output())) {
 867       *err = Err(function, "This tool's depend_output is bad.",
 868                  "It must match one of the outputs.");
 869       return Value();
 870     }
 871   }
 872   if ((!tool->link_output().empty() && tool->depend_output().empty()) ||
 873       (tool->link_output().empty() && !tool->depend_output().empty())) {
 874     *err = Err(function, "Both link_output and depend_output should either "
 875         "be specified or they should both be empty.");
 876     return Value();
 877   }
 878
 879   // Make sure there weren't any vars set in this tool that were unused.
 880   if (!block_scope.CheckForUnusedVars(err))
 881     return Value();
 882
 883   toolchain->SetTool(tool_type, tool.Pass());
 884   return Value();
 885 }
 886
 887 // toolchain_args --------------------------------------------------------------
 888
 889 extern const char kToolchainArgs[] = "toolchain_args";
 890 extern const char kToolchainArgs_HelpShort[] =
 891     "toolchain_args: Set build arguments for toolchain build setup.";
 892 extern const char kToolchainArgs_Help[] =
 893     "toolchain_args: Set build arguments for toolchain build setup.\n"
 894     "\n"
 895     "  Used inside a toolchain definition to pass arguments to an alternate\n"
 896     "  toolchain's invocation of the build.\n"
 897     "\n"
 898     "  When you specify a target using an alternate toolchain, the master\n"
 899     "  build configuration file is re-interpreted in the context of that\n"
 900     "  toolchain (see \"gn help toolchain\"). The toolchain_args function\n"
 901     "  allows you to control the arguments passed into this alternate\n"
 902     "  invocation of the build.\n"
 903     "\n"
 904     "  Any default system arguments or arguments passed in on the command-\n"
 905     "  line will also be passed to the alternate invocation unless explicitly\n"
 906     "  overridden by toolchain_args.\n"
 907     "\n"
 908     "  The toolchain_args will be ignored when the toolchain being defined\n"
 909     "  is the default. In this case, it's expected you want the default\n"
 910     "  argument values.\n"
 911     "\n"
 912     "  See also \"gn help buildargs\" for an overview of these arguments.\n"
 913     "\n"
 914     "Example:\n"
 915     "  toolchain(\"my_weird_toolchain\") {\n"
 916     "    ...\n"
 917     "    toolchain_args() {\n"
 918     "      # Override the system values for a generic Posix system.\n"
 919     "      is_win = false\n"
 920     "      is_posix = true\n"
 921     "\n"
 922     "      # Pass this new value for specific setup for my toolchain.\n"
 923     "      is_my_weird_system = true\n"
 924     "    }\n"
 925     "  }\n";
 926
 927 Value RunToolchainArgs(Scope* scope,
 928                        const FunctionCallNode* function,
 929                        const std::vector<Value>& args,
 930                        BlockNode* block,
 931                        Err* err) {
 932   // Find the toolchain definition we're executing inside of. The toolchain
 933   // function will set a property pointing to it that we'll pick up.
 934   Toolchain* toolchain = reinterpret_cast<Toolchain*>(
 935       scope->GetProperty(&kToolchainPropertyKey, nullptr));
 936   if (!toolchain) {
 937     *err = Err(function->function(),
 938                "toolchain_args() called outside of toolchain().",
 939                "The toolchain_args() function can only be used inside a "
 940                "toolchain() definition.");
 941     return Value();
 942   }
 943
 944   if (!args.empty()) {
 945     *err = Err(function->function(), "This function takes no arguments.");
 946     return Value();
 947   }
 948
 949   // This function makes a new scope with various variable sets on it, which
 950   // we then save on the toolchain to use when re-invoking the build.
 951   Scope block_scope(scope);
 952   block->Execute(&block_scope, err);
 953   if (err->has_error())
 954     return Value();
 955
 956   Scope::KeyValueMap values;
 957   block_scope.GetCurrentScopeValues(&values);
 958   toolchain->args() = values;
 959
 960   return Value();
 961 }
 962
 963 }  // namespace functions