zircon/public/gn/toolchain/environment.gni

# Copyright 2019 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//zircon/public/gn/config/standard.gni")
import("c_toolchain.gni")
import("environment_redirect.gni")
import("variants.gni")

declare_args() {
  # List of clauses to apply other GN build arguments to specific compilation
  # environments.  Each clause specifies matching criteria and arguments to
  # set in such environments.  Each matching clause is applied in order; each
  # argument it sets overrides any setting of that same argument in an earlier
  # matching clause or in the environment() declaration.  Note that if the
  # variant selected for a target via [`variants`](#variants) (which see) has
  # a `toolchain_args` setting, each argument therein will override the
  # settings here in `environment_args` clauses (within that variant
  # toolchain).
  #
  # Each clause is a scope.  The several parameters listed below are the
  # matching criteria.  All other parameters in a clause are the build
  # arguments set when that clause matches.  Note that these form a subset of
  # the matching criteria supported by [`variants`](#variants) selectors,
  # except for `tags` and `exclude_tags`.  The semantics of each criterion are
  # exactly the same here and there.
  #
  # For example:
  # ```
  #   environment_args = [ { kernel = true assert_level = 0 } ]
  # ```
  # sets `assert_level = 0` everywhere where `is_kernel == true`, while:
  # ```
  #   environment_args = [
  #     {
  #       kernel = false
  #       assert_level = 0
  #     },
  #     {
  #       kernel = true
  #       assert_level = 1
  #     },
  #     {
  #       environment = [ "efi" ]
  #       assert_level = 2
  #       optimize = "none"
  #     },
  #   ]
  # ```
  # sets `assert_level = 0` everywhere where `is_kernel == false`,
  # sets `assert_level = 1` most places where `is_kernel == true`,
  # but sets `assert_level = 2` and `optimize = "none"` in the "efi"
  # environment (where `is_kernel == true` also holds, but the later
  # clause overrides the preceding `assert_level = 1`).
  #
  # Clause scope parameters
  #
  #   * cpu
  #     - Optional: If nonempty, match only when $current_cpu is one in the
  #     - list.
  #     - Type: list(string)
  #
  #   * os
  #     - Optional: If nonempty, match only when $current_os is one in the
  #     - list.
  #     - Type: list(string)
  #
  #   * host
  #     - Optional: If present, match only in host environments if true or
  #     non-host environments if false.  This means a context in which
  #     $is_host is true, not specifically the build host.  For example, it
  #     would be true when cross-compiling host tools for an SDK build but
  #     would be false when compiling code for a hypervisor guest system
  #     that happens to be the same CPU and OS as the build host.
  #     - Type: bool
  #
  #   * kernel
  #     - Optional: If present, match only in kernel environments if true or
  #     non-kernel environments if false.  This means a context in which
  #     $is_kernel is true, not just the "kernel" environment itself.
  #     For different machine architectures there may be multiple different
  #     specialized environments that set $is_kernel, e.g. for boot loaders
  #     and for special circumstances used within the kernel.  See also the
  #     $tags field in $variant, described below.
  #     - Type: bool
  #
  #   * environment
  #     - Optional: If nonempty, a list of environment names that match.  This
  #     looks at ${toolchain.environment}, which is the simple name (no
  #     directories) in an environment label defined by environment().  Each
  #     element can match either the whole environment name, or just the
  #     "base" environment, which is the part of the name before a `.` if it
  #     has one.  For example, "host" would match both "host" and "host.fuzz".
  #     - Type: list(string)
  #
  #   * tags
  #     - Optional: If nonempty, a list of tags which must be present in the
  #     `tags` parameter to environment() for that environment to match.
  #     - Type: list(string)
  #     - Default: []
  #
  #   * exclude_tags
  #     - Optional: If nonempty, a list of tags which must *not* be present in
  #     the `tags` parameter to environment() for that environment to match.
  #     - Type: list(string)
  #     - Default: []
  #
  environment_args = []
}

# Define toolchains for a compilation environment.
#
# A compilation environment is the combination of a particular CPU, OS, and
# "execution environment".  The $target_name in environment() is the
# name of the execution environment, which identifies the circumstances in
# which code built with these toolchains runs.  Examples are:
#  * `host` for programs run during the build or by developers in an SDK
#  * `kernel` for the Zircon kernel
#  * `user` for user-mode programs running on top of Zircon/Fuchsia
# Additional environments are defined for more specialized purposes.
#
# The expansion of ":$target_name" is the ${toolchain.environment_label}
# value seen in these toolchains.  This is what must be suppled in
# environment_redirect()'s `environment_label` parameter.  The toolchains
# that make up the environment have labels that begin with this prefix
# and then append "-${variant}" or "-${variant}.shlib".
#
# Parameters
#
#   * cpu
#     - Required: $current_cpu value in the new toolchains.
#     - Type: string
#
#   * os
#     - Optional: $current_os value in the new toolchains.
#     - Type: string
#     - Default: "fuchsia"
#
#   * shlib
#     - Optional: If this environment will supported shared_library() and
#     loadable_module() targets via `.shlib` companion toolchains.
#     - Type: bool
#     - Default: false
#
#   * solink
#     - Optional: If this environment will be used *only* for shared_library()
#     and/or loadable_module() targets.  Mutually exclusive with $shlib.
#     - Type: bool
#     - Default: false
#
#   * configs
#     - Preset: $standard_configs
#     - Required: List of config() labels or scopes.
#     These are the default $configs preset in all compiling targets.
#     Elements are the same as $configs in a $variant scope in $variants.
#     Each element is usually a label (string), which means it's
#     in the preset $configs for all target scopes.  It can instead
#     be a scope that defines:
#       * shlib
#         - Optional: Boolean.  If defined, this element only takes effect
#         in the ${toolchain.shlib} toolchain (if true) or in the non-shlib
#         toolchain if false.
#       * types
#         - Optional: List of strings,  e.g. ["driver", "source_set"].
#         This element only takes effect for targets of these types.
#       * add, remove
#         - Optional: List of labels, usually config() targets.
#         The preset $configs gets `+=` and then `-=` these, respectively.
#
#   * implicit_deps
#     - Optional: List of labels or scopes.  This controls the list forcibly
#     added to the $deps list of every linking target built in this
#     environment.  Elements are the same as $implicit_deps in a @variant
#     scope in $variants.
#     - Type: list(label)
#     - Default: []
#
#   * globals
#     - Optional: A scope imported into the global scope in these toolchains.
#     This is the place to define `is_...` variables.
#
#   * tags
#     - Optional: A list of strings to appear in ${toolchain.tags}, along
#     with the `.tags` list from the variant (see $variants).  This has no
#     effect on which variants are available (see $exclude_variant_tags below).
#     It can supply additional tags that apply to every variant in this
#     environment.
#     - Type: list(string)
#     - Default: []
#
#   * toolchain_args
#     - Optional: A scope of build argument overrides for these toolchains.
#     This is just like $toolchain_args passed to toolchain() in bare GN.
#     Note that values set here might be overridden by user-chosen values
#     specified in [`environment_args`](#environment_args) or in variant
#     specs given in [`variants`](#variants).
#
#   * toolchain_vars
#     - Optional: A scope imported into the $toolchain scope in these
#     toolchains.  This can store useful toolchain-specific variables that
#     should be available within the toolchain.  $toolchain automatically
#     contains `tool_dir`, `tool_prefix`, `cc, and `cxx`, from
#     c_toolchain().  If `variant_suffix` is defined here, terminal targets
#     in the environment will have "$target_name$variant_suffix" aliases
#     that get the same thing but in that particular variant installed
#     under the suffixed name.  The default `variant_suffix` is ".$variant"
#     in each variant.
#
#   * variant_libprefix
#     - Optional: If true, each variant's name is used to form the
#     ${toolchain.libprefix} value in that variant.  The final libprefix
#     is "${toolchain_vars.libprefix}${toolchain.variant}/".  By default,
#     this is true *only* in variants that have the "instrumented" tag.
#     If explicitly set to true or false, that applies to *all* variants.
#     - Type: bool
#
#   * variant_selectors
#     - Optional: A list in the schema of the $variants build argument.  This
#     controls which variant is used to build each individual target.  Just
#     having a selector with `.variant = "..."` makes the "..." variant
#     toolchain exist in this environment, even if the selector doesn't
#     match anything.  Each `variant` scope can have its own $configs,
#     $implicit_deps, $globals, $toolchain_args, and $toolchain_vars that
#     are merged with the environment's (potentially overriding their
#     individual elements).
#     - Type: list(scope)
#     - Default: $variants + $default_variants + $standard_variants
#
#   * exclude_variant_tags
#     - Optional: A list of strings that might appear in the .tags list of a
#     .variant scope.  If any of these strings appears in a .variant scope,
#     then $variant_selectors elements using that variant will be silently
#     ignored in this environment's toolchains.  e.g. an environment that is
#     incompatbile with instrumentation could list the "instrumented" tag
#     and variants that enable instrumentation will be defined with that tag.
#     Then simple `variants=["asan"]` user configurations that would apply
#     ordinarily to all targets don't break the special-case execution
#     environments (vdso, bootloader, etc).
#
template("environment") {
  assert(current_toolchain == default_toolchain,
         "environment() should only be used in $default_toolchain")

  # These are seen by c_toolchain(), below.
  environment = target_name
  environment_label = get_label_info(":$target_name", "label_no_toolchain")

  # For "host.fuzz", the base is "host".
  base_environment = get_path_info(environment, "name")

  # Name construction logic must match environment_redirect.gni.
  toolchain_base_name = "${environment}-${invoker.cpu}"

  # These will be seen by c_toolchain() below.
  shlib = defined(invoker.shlib) && invoker.shlib

  if (defined(invoker.os)) {
    env_os = invoker.os
  } else {
    env_os = "fuchsia"
  }

  # For all host environments include the OS to distinguish one from
  # another.  For other environments, it's implicit when it's "fuchsia"
  # and when it exactly matches the base environment name (e.g. "efi").
  if (base_environment == "host" ||
      (env_os != "fuchsia" && env_os != base_environment)) {
    toolchain_base_name += "-${invoker.os}"
  }

  # The canonicalized list of selectors.  Each element is in the schema of
  # $variant elements, but canonicalized to simplify the matching code: all
  # fields are present (defaults of []); .variant is always a simple string
  # (of those in $_variant_names, below).
  variant_selectors = []

  # The environment can have its own list of selectors.
  # Most environments use the globally-configured $variants list.
  if (defined(invoker.variant_selectors)) {
    raw_selectors = invoker.variant_selectors
  } else {
    raw_selectors = variants + default_variants + standard_variants
  }

  if (defined(invoker.tags)) {
    env_tags = invoker.tags
  } else {
    env_tags = []
  }

  # First expand the plain-string shorthand selectors to full scopes.
  selectors = []
  foreach(selector, raw_selectors) {
    if (selector == "$selector") {
      # A string selector is a shorthand.
      # First check for a simple shorthand from the global list.
      foreach(shorthand, variant_shorthands) {
        if (selector == shorthand.name) {
          selectors += shorthand.selectors
          selector = false
        }
      }
    }
    if (selector == "$selector") {
      selector = {
        host = false
        if (selector == get_path_info(selector, "file")) {
          # No slash in the name.  Just a trivial non-host catch-all.
          variant = selector
        } else {
          # "$variant/$output_name"
          variant = get_path_info(selector, "dir")
          output_name = [ get_path_info(selector, "file") ]
        }
      }
    }
    if (selector != false) {
      selectors += [ selector ]
    }
  }

  # Needed below because a.b.c doesn't work in GN.
  g = {
  }
  if (defined(invoker.globals)) {
    g = invoker.globals
  }

  # This pass canonicalizes the selectors and collects the variant specs.
  defined_variant_names = []
  variant_names = []
  variant_specs = []
  foreach(selector, selectors) {
    assert(defined(selector.variant),
           "`variants` selector missing `.variant`: $selector")

    foreach(variant, [ selector.variant ]) {
      if (variant != false && variant != "$variant") {
        # This selector is defining a variant.  Record the variant spec and
        # name and then update the selector to use just the name.
        assert(defined(variant.name),
               "`variants` element .variant scope missing .name: $selector")
        assert(
            defined_variant_names + [ variant.name ] - [ variant.name ] ==
                defined_variant_names,
            "`variants` element overrides variant ${variant.name}: $selector")
        defined_variant_names += [ variant.name ]
        variant_names += [ variant.name ]
        variant_specs += [ variant ]
        sel_variant = variant.name
      } else {
        sel_variant = variant

        # Add this to the list of needed variants if it's not there already.
        variant_names += [ variant ]
        variant_names -= [ variant ]
        variant_names += [ variant ]
      }
    }

    sel = {
      # Clear from previous iteration.
    }
    sel = {
      # Set defaults for all the list fields and then clobber a subset of
      # those with whatever the selector actually included.  The boolean
      # fields are not defaulted this way because for them neither false
      # nor true means the same thing as the field being omitted.
      cpu = []
      dir = []
      environment = []
      label = []
      name = []
      os = []
      output_name = []
      target_type = []
      forward_variables_from(selector,
                             "*",
                             [
                               "toolchain",
                               "variant",
                             ])
    }

    # If the selector filters on environment, then don't bother including
    # it if it will never match in the environment we're defining.
    if (sel.environment != [] && (sel.environment + [ environment ] -
                                  [ environment ] == sel.environment &&
                                  sel.environment + [ base_environment ] -
                                  [ base_environment ] == sel.environment)) {
      sel = {
      }
    }

    # Same for standard shorthands.
    if ((defined(sel.host) && sel.host != (defined(g.is_host) && g.is_host)) ||
        (defined(sel.kernel) &&
         sel.kernel != (defined(g.is_kernel) && g.is_kernel))) {
      sel = {
      }
    }

    if (sel != {
        }) {
      sel.variant = sel_variant

      # When the selector matches, redirect to this toolchain.
      sel.toolchain = get_label_info(":${toolchain_base_name}-${sel_variant}",
                                     "label_no_toolchain")
      if (shlib) {
        sel.shlib_toolchain = "${sel.toolchain}.shlib"
      }

      variant_selectors += [ sel ]
    }
  }

  # variant_names now lists all the variants that might be needed in this
  # environment.  toolchain_variants will collect all the canonicalized
  # variant specs that control which toolchains actually get defined below.
  toolchain_variants = []

  # In the first pass, each variant spec is canonicalized, and then
  # appended to toolchain_variants if it's complete.  An incomplete variant
  # has a nonempty .bases list that will be resolved in the second pass;
  # these are appended to incomplete_variants instead.
  incomplete_variants = []
  foreach(raw_spec, variant_specs) {
    spec = {
      # Clear from previous iteration.
    }
    spec = {
      bases = []
      configs = []
      implicit_deps = []
      tags = []
      globals = {
      }
      toolchain_args = {
      }
      toolchain_vars = {
      }
      forward_variables_from(raw_spec, "*")
    }
    if (spec.bases == []) {
      toolchain_variants += [ spec ]
    } else {
      incomplete_variants += [ spec ]
      variant_names += spec.bases
    }
  }

  # In the final pass, the incomplete variants are expanded with
  # reference to the complete variants.
  foreach(incomplete, incomplete_variants) {
    bases = []  # Clear from previous iteration.
    foreach(base, incomplete.bases) {
      assert(base == "$base",
             ".variant.base elements must be strings: $incomplete")
      assert(toolchain_variants + [ base ] - [ base ] == toolchain_variants,
             ".variant.base elements must be complete themselves: $incomplete")
      foreach(complete, toolchain_variants) {
        if (base == complete.name) {
          bases += [ complete ]
        }
      }
    }
    bases += [ incomplete ]
    toolchain_variants += [
      {
        name = incomplete.name

        # Append each list from all the bases.
        configs = []
        implicit_deps = []
        tags = []
        foreach(base, bases) {
          configs += base.configs
          implicit_deps += base.implicit_deps
          tags += base.tags
          tags -= base.tags
          tags += base.tags
        }

        # Merge each scope from all the bases.
        globals = {
          foreach(base, bases) {
            forward_variables_from(base.globals, "*")
          }
        }
        toolchain_args = {
          foreach(base, bases) {
            forward_variables_from(base.toolchain_args, "*")
          }
        }
        toolchain_vars = {
          foreach(base, bases) {
            forward_variables_from(base.toolchain_vars, "*")
          }
        }
      },
    ]
  }

  # Now we have toolchain_variants and variant_selectors in canonical form.
  # See if there are any we should cull from the list.
  exclude_variant_tags = []
  if (defined(invoker.exclude_variant_tags)) {
    exclude_variant_tags += invoker.exclude_variant_tags
  }
  if (defined(g.is_kernel) && g.is_kernel) {
    exclude_variant_tags += [ "useronly" ]
  } else {
    exclude_variant_tags += [ "kernel" ]
  }

  # Weed out the variants that this environment silently excludes.
  excluded_variants = []
  included_variants = []
  foreach(variant, toolchain_variants) {
    if (exclude_variant_tags + variant.tags - variant.tags !=
        exclude_variant_tags) {
      excluded_variants += [ variant.name ]
      toolchain_variants -= [ variant ]
    } else {
      included_variants += [ variant.name ]
    }
  }
  if (excluded_variants != []) {
    # Weed out the selectors that would choose an excluded variant.
    excluded_selectors = []
    foreach(selector, variant_selectors) {
      if (excluded_variants + [ selector.variant ] - [ selector.variant ] !=
          excluded_variants) {
        excluded_selectors += [ selector ]
        excluded_selectors -= [ selector ]
        excluded_selectors += [ selector ]
      }
    }
    variant_selectors -= excluded_selectors
  }

  # Now excluded_variants lists toolchain names we know we never actually
  # want to compile anything in.  However, environment_redirect() has to
  # pick a default to redirect through even though it has no way to see
  # exclude_variant_tags or the other factors that make this environment
  # actually exclude a variant.  So, the first likely-looking one in
  # $default_variants has to exist so it can redirect to the right one.
  # When the one it would choose is in excluded_variants, we need to make
  # that toolchain exist as a dummy for those redirects.
  #
  # Furthermore, in case $variant_selectors for this environment()
  # doesn't include $default_variants, we need to treat that "first
  # likely-looking one" the same way so environment_redirect() works.
  redirect_default = ""

  # **NOTE:** This code must be kept in synch with the corresponding loop
  # in environment_redirect().
  foreach(default, default_variants) {
    if (redirect_default == "") {
      if (default == "$default") {
        foreach(shorthand, variant_shorthands) {
          if (default != "" &&
              (default == shorthand.name ||
               get_path_info(default, "dir") == shorthand.name)) {
            default = ""
          }
        }
        if (default != "") {
          default = {
            variant = default
          }
        }
      }
      if (default != "" &&
          (!defined(default.environment) || default.environment == [] ||
           default.environment + [ environment ] - [ environment ] !=
           default.environment ||
           default.environment + [ base_environment ] - [ base_environment ] !=
           default.environment)) {
        redirect_default = default.variant
      }
    }
  }
  assert(redirect_default != "",
         "BUG: failed to deduce a default variant!" +
             " check this code against environment_redirect() ???")

  # If it's included we don't have to do anything.
  if (included_variants + [ redirect_default ] - [ redirect_default ] ==
      included_variants) {
    # Define an additional toolchain under the expected name.  It may wind
    # up instantiating a lot of targets, which is unfortunate since its
    # only purpose is to resolve redirect group() targets.  But to make
    # sure nothing goes awry because the code evaluated is confused by
    # wrong toolchain definitions, make it a copy in all but name of a
    # variant where we actually do expect to instantiate and build targets.
    toolchain_variants += [
      {
        forward_variables_from(toolchain_variants[0], "*", [ "name" ])
        name = redirect_default
      },
    ]
  }

  # Reuse the selectors local so we can shadow variant_selectors below.
  # Also annotate each selector with its variant's tags for the
  # $exclude_variant_tags parameter to _variant_target() to match against.
  selectors = []
  foreach(selector, variant_selectors) {
    selectors += [
      {
        forward_variables_from(selector, "*")
        assert(!defined(tags))
        foreach(variant, toolchain_variants) {
          if (variant.name == selector.variant) {
            tags = env_tags + variant.tags
          }
        }
        assert(defined(tags),
               "environment(\"$target_name\") variant_selectors element" +
                   " references undefined variant \"${selector.variant}\"")
      },
    ]
  }
  variant_selectors = []

  env_tc_args = {
  }
  foreach(selector, environment_args) {
    # An empty selector always matches, so start with the flag set.
    # Each `if` block below applies each inclusion criterion: if it's
    # present and it does not include this target, then clear the flag.
    selector_matches = true

    if (defined(selector.cpu) && selector.cpu != []) {
      if (selector.cpu + [ invoker.cpu ] - [ invoker.cpu ] == selector.cpu) {
        selector_matches = false
      }
    }
    if (defined(selector.environment) && selector.environment != []) {
      if (selector.environment + [ environment ] - [ environment ] ==
          selector.environment &&
          selector.environment + [ base_environment ] - [ base_environment ] ==
          selector.environment) {
        selector_matches = false
      }
    }
    if (defined(selector.os) && selector.os != []) {
      if (selector.os + [ env_os ] - [ env_os ] == selector.os) {
        selector_matches = false
      }
    }
    if (defined(selector.tags) && selector.tags != []) {
      if (selector.tags + [ env_tags ] - [ env_tags ] == selector.tags) {
        selector_matches = false
      }
    }
    if (defined(selector.exclude_tags) && selector.exclude_tags != []) {
      if (selector.exclude_tags + [ env_tags ] - [ env_tags ] !=
          selector.exclude_tags) {
        selector_matches = false
      }
    }
    if (defined(selector.host) &&
        selector.host != (defined(g.is_host) && g.is_host)) {
      selector_matches = false
    }
    if (defined(selector.kernel) &&
        selector.kernel != (defined(g.is_kernel) && g.is_kernel)) {
      selector_matches = false
    }

    if (selector_matches) {
      # Add the settings in this selector to the collected set.  The same
      # argument in a later selector overrides that argument in an earlier one.
      new_env_tc_args = {
        forward_variables_from(env_tc_args, "*")
        forward_variables_from(selector,
                               "*",
                               [
                                 "cpu",
                                 "environment",
                                 "exclude_tags",
                                 "host",
                                 "kernel",
                                 "os",
                                 "tags",
                               ])
      }
      env_tc_args = {
      }
      env_tc_args = new_env_tc_args
      new_env_tc_args = {  # Clear it before the next iteration.
      }
    }
  }

  # Define a primary toolchain, and possibly also a shlib toolchain, for each
  # variant.  If there are two, both toolchains get a ${toolchain.shlib} value
  # pointing to the shlib toolchain.  Any ${toolchain.configs} elements that
  # use `.shlib = true` will affect the preset configs in ${toolchain.shlib}
  # differently and then both shared_library() and loadable_module() in the
  # primary toolchain redirect to the shlib toolchain.
  foreach(variant, toolchain_variants) {
    toolchains = []  # Clear from previous iteration.

    tc_name = "${toolchain_base_name}-${variant.name}"
    toolchains = [
      {
        name = tc_name
        if (shlib) {
          shlib_name = "${name}.shlib"
        }
      },
    ]
    if (shlib) {
      toolchains += [
        {
          name = "${tc_name}.shlib"
          shlib_name = name
        },
      ]
    }

    foreach(tc, toolchains) {
      # Canonicalize the ${toolchain.configs} list.
      #
      # This is used by //zircon/public/gn/BUILDCONFIG.gn for set_defaults().
      # The labels must be absolute since they will be used all over in
      # the new toolchain, not just where the environment() is.
      #
      tc_configs = []
      foreach(config, invoker.configs + variant.configs) {
        if (config == "$config") {
          tc_configs += [ get_label_info(config, "label_no_toolchain") ]
        } else {
          # It's actually a scope.  Check if its shlib constraint matches.
          # Testing the inverted expression against !config.shlib
          # constitutes an assert that config.shlib is a proper Boolean.
          if (!defined(config.shlib) ||
              !config.shlib ==
              !(defined(tc.shlib_name) && tc.name == tc.shlib_name)) {
            # Expand its add and remove lists.
            tc_configs += [
              {
                forward_variables_from(config, [ "types" ])
                add = []
                if (defined(config.add)) {
                  foreach(label, config.add) {
                    add += [ get_label_info(label, "label_no_toolchain") ]
                  }
                }
                remove = []
                if (defined(config.remove)) {
                  foreach(label, config.remove) {
                    remove += [ get_label_info(label, "label_no_toolchain") ]
                  }
                }
                assert(add != [] || remove != [], "useless $config")
              },
            ]
          }
        }
      }

      # Likewise for the ${toolchain.implicit_deps} list.  This is used by
      # the various linking target types, where it's forcibly appended to
      # $deps rather than pre-set via set_defaults() as $configs is.
      raw_implicit_deps = []
      if (defined(invoker.implicit_deps)) {
        raw_implicit_deps += invoker.implicit_deps
      }
      raw_implicit_deps += variant.implicit_deps
      tc_implicit_deps = []
      foreach(dep, raw_implicit_deps) {
        if (dep == "$dep") {
          tc_implicit_deps += [ get_label_info(dep, "label_no_toolchain") ]
        } else if (!defined(dep.shlib) || !dep.shlib ||
                   (defined(tc.shlib_name) && tc.name == tc.shlib_name)) {
          # It's actually a scope.
          # Expand its add and remove lists.
          tc_implicit_deps += [
            {
              forward_variables_from(dep, [ "types" ])
              add = []
              if (defined(dep.add)) {
                foreach(label, dep.add) {
                  add += [ get_label_info(label, "label_no_toolchain") ]
                }
              }
              remove = []
              if (defined(dep.remove)) {
                foreach(label, dep.remove) {
                  remove += [ get_label_info(label, "label_no_toolchain") ]
                }
              }
              unless_configs = []
              if (defined(dep.unless_configs)) {
                foreach(label, dep.unless_configs) {
                  unless_configs +=
                      [ get_label_info(label, "label_no_toolchain") ]
                }
              }
              assert(add != [] || remove != [], "useless $dep")
            },
          ]
        }
      }

      # Merge the $globals scopes from the invoker and the variant.
      tc_globals = {
      }
      tc_globals = {
        forward_variables_from(g, "*")
        if (defined(variant.globals)) {
          forward_variables_from(variant.globals, "*")
        }
      }

      c_toolchain(tc.name) {
        cpu = invoker.cpu
        os = env_os
        shlib = shlib || (defined(invoker.solink) && invoker.solink)
        toolchain_args = {
          if (defined(invoker.toolchain_args)) {
            forward_variables_from(invoker.toolchain_args,
                                   "*",
                                   [
                                     "current_cpu",
                                     "current_os",
                                     "toolchain",
                                   ])
          }

          # environment_args overrides environment() parameters.
          forward_variables_from(env_tc_args,
                                 "*",
                                 [
                                   "current_cpu",
                                   "current_os",
                                   "toolchain",
                                 ])

          # variants overrides environment_args.
          if (defined(variant.toolchain_args)) {
            forward_variables_from(variant.toolchain_args,
                                   "*",
                                   [
                                     "current_cpu",
                                     "current_os",
                                     "toolchain",
                                   ])
          }
        }
        toolchain_vars = {
          # ${toolchain.environment} and ${toolchain.environment_label}
          # will identify the environment within its own toolchains.
          base_environment = base_environment
          environment = environment
          environment_label = environment_label

          if (defined(tc.shlib_name)) {
            shlib = get_label_info(":${tc.shlib_name}", "label_no_toolchain")

            # Override the .label set by c_toolchain(), so it refers
            # to the base toolchain, not the shlib toolchain.
            label = get_label_info(":$tc_name", "label_no_toolchain")
          }

          configs = tc_configs
          implicit_deps = tc_implicit_deps
          globals = tc_globals

          # Both the invoker and the variant can supply a $toolchain_vars
          # scope for whatever they want to see in $toolchain, but they
          # cannot set the things we set directly.
          if (defined(invoker.toolchain_vars)) {
            forward_variables_from(invoker.toolchain_vars,
                                   "*",
                                   [
                                     "configs",
                                     "base_environment",
                                     "environment",
                                     "environment_label",
                                     "globals",
                                     "implicit_deps",
                                     "label",
                                     "shlib",
                                     "strip",
                                     "variant",
                                     "variant_selectors",
                                   ])
          }
          if (defined(variant.toolchain_vars)) {
            forward_variables_from(variant.toolchain_vars,
                                   "*",
                                   [
                                     "configs",
                                     "base_environment",
                                     "environment",
                                     "environment_label",
                                     "globals",
                                     "implicit_deps",
                                     "label",
                                     "shlib",
                                     "strip",
                                     "variant",
                                     "variant_selectors",
                                   ])
          }

          # Plumb through the canonicalized $variants list for
          # _variant_target() to match against.
          variant_selectors = selectors

          # Plumb through the list of tags from this variant.
          tags = env_tags + variant.tags

          # Finally, set .variant to the simple name string for the
          # variant.  (This now shadows the template-scope variable
          # `variant`, so it can't be used any more in this block.)
          variant = variant.name

          if (!defined(libprefix)) {
            libprefix = ""
          }
          if ((defined(invoker.variant_libprefix) &&
               invoker.variant_libprefix) ||
              (!defined(invoker.variant_libprefix) &&
               tags + [ "instrumented" ] - [ "instrumented" ] != tags)) {
            libprefix += "$variant/"
          }

          # Plumb through the suffix of this variant and the list of others.
          if (!defined(variant_suffix)) {
            variant_suffix = ".$variant"
          }

          other_variants = []
          foreach(other_variant, toolchain_variants) {
            if (other_variant.name != variant) {
              other_variants += [
                {
                  label = get_label_info(
                          ":${toolchain_base_name}-${other_variant.name}",
                          "label_no_toolchain")
                  if (defined(other_variant.variant_suffix)) {
                    suffix = other_variant.variant_suffix
                  } else {
                    suffix = ".${other_variant.name}"
                  }
                },
              ]
            }
          }
        }

        # Translate in-toolchain settings to toolchain-defining settings.
        gcc = defined(tc_globals.is_gcc) && tc_globals.is_gcc
        if (defined(toolchain_args.use_goma)) {
          use_goma = toolchain_args.use_goma
        }

        forward_variables_from(invoker, [ "strip" ])
        if (gcc && defined(strip) && strip == "--strip-sections") {
          # GNU strip/objcopy doesn't support --strip-sections.
          strip = true
        }

        host = defined(g.is_host) && g.is_host
      }
    }
  }
}

set_defaults("environment") {
  configs = standard_configs
  implicit_deps = []
}

# Define environments based on $standard_environments.
#
# $target_name is a suffix on the `name` fields in $standard_environments
# elements and must start with ".".  Parameters are generally as for
# environment() except $cpu and $os cannot be set and $configs has
# $standard_configs (and others) prepended rather than being preset.
template("standard_environments") {
  assert(target_name == "" || get_path_info(target_name, "extension") != "",
         "standard_environments() name must start with `.`")

  foreach(env, standard_environments) {
    env_name = env.name + target_name

    foreach(target, env.targets) {
      environment(env_name) {
        forward_variables_from(target, "*")
        forward_variables_from(env,
                               "*",
                               [
                                 "configs",
                                 "name",
                                 "targets",
                               ])

        # Let the invoker clobber most settings.
        forward_variables_from(invoker,
                               "*",
                               [
                                 "configs",
                                 "cpu",
                                 "implicit_deps",
                                 "os",
                                 "tags",
                               ])

        # The invoker can have used `configs -=` to remove some of the
        # default configs set above.  Now append the base environment's
        # configs and the invoker's.
        if (defined(env.configs)) {
          configs += env.configs
        }
        if (defined(invoker.configs)) {
          configs += invoker.configs
        }

        # Append the invoker's implicit_deps to those provided by the base
        # environment.
        if (defined(invoker.implicit_deps)) {
          implicit_deps += invoker.implicit_deps
        }

        # Likewise for tags.
        tags = []
        if (defined(env.tags)) {
          tags += env.tags
        }
        if (defined(invoker.tags)) {
          tags += invoker.tags
        }
      }
    }
  }
}