public/gn/toolchain/environment.gni - zircon - Git at Google

 # 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("$zx/public/gn/config/standard.gni")
 import("c_toolchain.gni")

 declare_args() {
   # TODO: doc
   variants = []
 }

 # Define toolchains for a compilation environment.
 #
 # A compilation environment is the combination of a particular CPU, OS, and
 # "execution environment".  The $target_name in define_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
 # select_toolchain()'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.
 #
 #   os
 #     Optional: $current_os value in the new toolchains.
 #     Default: "fuchsia"
 #
 #   shlib
 #     Optional: If this environment will supported shared_library() and
 #     loadable_module() targets via `.shlib` companion toolchains.
 #     Default: false
 #
 #   solink
 #     Optional: If this environment will be used *only* for shared_library()
 #     and/or loadable_module() targets.  Mutually exclusive with $shlib.
 #     Default: false
 #
 #   configs
 #     Preset: $standard_configs
 #     Required: List of labels or scopes, usually config() targets.
 #     These are the default $configs preset in all compiling targets.
 #     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 true, this element only takes effect
 #         in the ${toolchain.shlib} toolchain.
 #         Default: 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.
 #
 #   globals
 #     Optional: A scope imported into the global scope in these toolchains.
 #     This is the place to define `is_...` variables.
 #
 #   toolchain_args
 #     Optional: A scope of build argument overrides for these toolchains.
 #     This is just like $toolchain_args passed to toolchain() in bare GN.
 #
 #   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 define_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_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,
 #     $globals, $toolchain_args, and $toolchain_vars that are merged with
 #     the environment's (potentially overriding their individual elements).
 #     Note: select_toolchain() with `environment_label` set to this
 #     environment may not work if this does not include $default_variants.
 #     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 "instrumentation" 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("define_environment") {
   assert(current_toolchain == default_toolchain,
          "define_environment() should only be used in $default_toolchain")

   # These are seen by define_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 select_toolchain.gni.
   toolchain_base_name = "${environment}-${invoker.cpu}"

   # For host environments include the OS to distinguish one from another.
   # For other environments, the OS is implicit (i.e. "fuchsia" modulo EFI).
   if (base_environment == "host") {
     toolchain_base_name += "-${invoker.os}"
   }

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

   # 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
   }

   # 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") {
       if (selector == get_path_info(selector, "file")) {
         # No slash in the name.  Just a trivial non-host catch-all.
         selector = {
           variant = selector
           host = false
         }
       } else {
         # "$variant/$output_name"
         selector = {
           variant = get_path_info(selector, "dir")
           output_name = [ get_path_info(selector, "file") ]
         }
         assert(false, "TODO: shorthand expansion")
       }
     }
     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 = []
       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 = []
         tags = []
         foreach(base, bases) {
           configs += base.configs
           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" ]
   }
   if (exclude_variant_tags != []) {
     # Weed out the variants that this environment silently excludes.
     excluded_variants = []
     foreach(variant, toolchain_variants) {
       if (exclude_variant_tags + variant.tags - variant.tags !=
           exclude_variant_tags) {
         excluded_variants += [ variant.name ]
         toolchain_variants -= [ variant ]
       }
     }
     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
     }
   }

   # Reuse the selectors local so we can shadow variant_selectors below.
   selectors = []
   selectors = variant_selectors
   variant_selectors = []

   # 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 $zx/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 define_environment() is.
       tc_configs = []
       foreach(config, invoker.configs + variant.configs) {
         if (config == "$config") {
           tc_configs += [ get_label_info(config, "label_no_toolchain") ]
         } else if (!defined(config.shlib) || !config.shlib ||
                    (defined(tc.shlib_name) && tc.name == tc.shlib_name)) {
           # It's actually a scope.
           # 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")
             },
           ]
         }
       }

       # 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, "*")
         }
       }

       define_c_toolchain(tc.name) {
         cpu = invoker.cpu
         if (defined(invoker.os)) {
           os = invoker.os
         } else {
           os = "fuchsia"
         }
         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",
                                    ])
           }
           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 define_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
           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",
                                      "label",
                                      "shlib",
                                      "strip",
                                      "variant",
                                      "variant_selectors",
                                    ])
           }
           if (defined(variant.toolchain_vars)) {
             forward_variables_from(variant.toolchain_vars,
                                    "*",
                                    [
                                      "configs",
                                      "base_environment",
                                      "environment",
                                      "environment_label",
                                      "globals",
                                      "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 = 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

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

           if (!defined(libprefix)) {
             libprefix = ""
           }

           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("define_environment") {
   configs = standard_configs
 }

 # 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
 # define_environment() except $cpu and $os cannot be set and $configs has
 # $standard_configs (and others) prepended rather than being preset.
 #
 template("define_standard_environments") {
   assert(target_name == "" || get_path_info(target_name, "extension") != "",
          "define_standard_environments() name must start with `.`")
   foreach(env, standard_environments) {
     foreach(target, env.targets) {
       define_environment("${env.name}${target_name}") {
         forward_variables_from(target, "*")
         forward_variables_from(env,
                                "*",
                                [
                                  "configs",
                                  "name",
                                  "targets",
                                ])

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

         # 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
         }
       }
     }
   }
 }
	# 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("$zx/public/gn/config/standard.gni")
	import("c_toolchain.gni")

	declare_args() {
	# TODO: doc
	variants = []
	}

	# Define toolchains for a compilation environment.
	#
	# A compilation environment is the combination of a particular CPU, OS, and
	# "execution environment". The $target_name in define_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
	# select_toolchain()'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.
	#
	# os
	# Optional: $current_os value in the new toolchains.
	# Default: "fuchsia"
	#
	# shlib
	# Optional: If this environment will supported shared_library() and
	# loadable_module() targets via `.shlib` companion toolchains.
	# Default: false
	#
	# solink
	# Optional: If this environment will be used only for shared_library()
	# and/or loadable_module() targets. Mutually exclusive with $shlib.
	# Default: false
	#
	# configs
	# Preset: $standard_configs
	# Required: List of labels or scopes, usually config() targets.
	# These are the default $configs preset in all compiling targets.
	# 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 true, this element only takes effect
	# in the ${toolchain.shlib} toolchain.
	# Default: 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.
	#
	# globals
	# Optional: A scope imported into the global scope in these toolchains.
	# This is the place to define `is_...` variables.
	#
	# toolchain_args
	# Optional: A scope of build argument overrides for these toolchains.
	# This is just like $toolchain_args passed to toolchain() in bare GN.
	#
	# 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 define_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_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,
	# $globals, $toolchain_args, and $toolchain_vars that are merged with
	# the environment's (potentially overriding their individual elements).
	# Note: select_toolchain() with `environment_label` set to this
	# environment may not work if this does not include $default_variants.
	# 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 "instrumentation" 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("define_environment") {
	assert(current_toolchain == default_toolchain,
	"define_environment() should only be used in $default_toolchain")

	# These are seen by define_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 select_toolchain.gni.
	toolchain_base_name = "${environment}-${invoker.cpu}"

	# For host environments include the OS to distinguish one from another.
	# For other environments, the OS is implicit (i.e. "fuchsia" modulo EFI).
	if (base_environment == "host") {
	toolchain_base_name += "-${invoker.os}"
	}

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

	# 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
	}

	# 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") {
	if (selector == get_path_info(selector, "file")) {
	# No slash in the name. Just a trivial non-host catch-all.
	selector = {
	variant = selector
	host = false
	}
	} else {
	# "$variant/$output_name"
	selector = {
	variant = get_path_info(selector, "dir")
	output_name = [ get_path_info(selector, "file") ]
	}
	assert(false, "TODO: shorthand expansion")
	}
	}
	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 = []
	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 = []
	tags = []
	foreach(base, bases) {
	configs += base.configs
	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" ]
	}
	if (exclude_variant_tags != []) {
	# Weed out the variants that this environment silently excludes.
	excluded_variants = []
	foreach(variant, toolchain_variants) {
	if (exclude_variant_tags + variant.tags - variant.tags !=
	exclude_variant_tags) {
	excluded_variants += [ variant.name ]
	toolchain_variants -= [ variant ]
	}
	}
	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
	}
	}

	# Reuse the selectors local so we can shadow variant_selectors below.
	selectors = []
	selectors = variant_selectors
	variant_selectors = []

	# 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 $zx/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 define_environment() is.
	tc_configs = []
	foreach(config, invoker.configs + variant.configs) {
	if (config == "$config") {
	tc_configs += [ get_label_info(config, "label_no_toolchain") ]
	} else if (!defined(config.shlib) \|\| !config.shlib \|\|
	(defined(tc.shlib_name) && tc.name == tc.shlib_name)) {
	# It's actually a scope.
	# 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")
	},
	]
	}
	}

	# 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, "*")
	}
	}

	define_c_toolchain(tc.name) {
	cpu = invoker.cpu
	if (defined(invoker.os)) {
	os = invoker.os
	} else {
	os = "fuchsia"
	}
	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",
	])
	}
	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 define_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
	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",
	"label",
	"shlib",
	"strip",
	"variant",
	"variant_selectors",
	])
	}
	if (defined(variant.toolchain_vars)) {
	forward_variables_from(variant.toolchain_vars,
	"*",
	[
	"configs",
	"base_environment",
	"environment",
	"environment_label",
	"globals",
	"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 = 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

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

	if (!defined(libprefix)) {
	libprefix = ""
	}

	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("define_environment") {
	configs = standard_configs
	}

	# 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
	# define_environment() except $cpu and $os cannot be set and $configs has
	# $standard_configs (and others) prepended rather than being preset.
	#
	template("define_standard_environments") {
	assert(target_name == "" \|\| get_path_info(target_name, "extension") != "",
	"define_standard_environments() name must start with `.`")
	foreach(env, standard_environments) {
	foreach(target, env.targets) {
	define_environment("${env.name}${target_name}") {
	forward_variables_from(target, "*")
	forward_variables_from(env,
	"*",
	[
	"configs",
	"name",
	"targets",
	])

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

	# 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
	}
	}
	}
	}
	}