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

declare_args() {
  # List of "selectors" to request variant builds of certain targets.  Each
  # selector specifies matching criteria and a chosen variant.  The first
  # selector in the list to match a given target determines which variant is
  # used for that target.
  #
  # The $default_variants list is appended to the list set here.  So if no
  # selector set in $variants matches (e.g. if the list is empty, as is the
  # default), then the first match in $default_variants chooses the variant.
  #
  # Each selector is either a string or a scope.  A selector that's a string
  # is a shorthand that gets expanded to a full selector (a scope); the full
  # selector form is described below.
  #
  # If a string selector contains a slash, then it's "shorthand/filename".
  # This is like the plain "shorthand" selector, but further constrained to
  # apply only to a binary whose `output_name` exactly matches "filename".
  #
  # The "shorthand" string (a whole string selector or the part before slash)
  # is first looked up in $variant_shorthands, which see.  If it doesn't match
  # a name defined there, then it must be the name of a variant.  In that case,
  # it's equivalent to `{ variant = "..." host = false }`, meaning it applies
  # to every binary not built to be a host tool.
  #
  # A full selector is a scope with the following fields.  All the fields
  # other than `.variant` are matching criteria.  A selector matches if all of
  # its matching criteria match.  Hence, a selector with no criteria defined
  # always matches and is referred to as a "catch-all".  The $default_variants
  # list ends with a catch-all, so each target always chooses some variant.
  #
  # Selector scope parameters
  #
  #   * variant
  #     - Required: The variant to use when this selector matches.  If this
  #     is a string then it must match a fully-defined variant elsewhere in
  #     the list (or in $default_variants + $standard_variants, which is
  #     appended implicitly to the $variants list).  If it's a scope then
  #     it defines a new variant (see details below).
  #     - Type: string or scope, described below
  #
  #   * 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)
  #
  #   * target_type
  #     - Optional: If nonempty, a list of target types to match.  This is
  #     one of "executable", "host_tool", "loadable_module", "driver", or
  #     "test".
  #     Note, test_driver() matches as "driver".
  #     - Type: list(string)
  #
  #   * label
  #     - Optional: If nonempty, match only when the canonicalized target label
  #     (as returned by `get_label_info(..., "label_no_toolchain")`) is one in
  #     the list.
  #     - Type: list(label_no_toolchain)
  #
  #   * dir
  #     - Optional: If nonempty, match only when the directory part of the
  #     target label (as returned by `get_label_info(..., "dir")`) is one in
  #     the list.
  #     - Type: list(label_no_toolchain)
  #
  #   * name
  #     - Optional: If nonempty, match only when the name part of the target
  #     label (as returned by `get_label_info(..., "name")`) is one in the
  #     list.
  #     - Type: list(label_no_toolchain)
  #
  #   * output_name
  #     - Optional: If nonempty, match only when the `output_name` of the
  #     target is one in the list.  Note `output_name` defaults to
  #     `target_name`, and does not include prefixes or suffixes like ".so"
  #     or ".exe".
  #     - Type: list(string)
  #
  # An element with a scope for `.variant` defines a new variant.  Each
  # variant name used in a selector must be defined exactly once.  Other
  # selectors can refer to the same variant by using the name string in the
  # `.variant` field.  Definitions in $variants take precedence over the same
  # name defined in $standard_variants, but it would probably cause confusion
  # to use the name of a standard variant with a non-standard definition.
  #
  # Variant scope parameters
  #
  #   * name
  #     - Required: Name for the variant.  This must be unique among all
  #     variants used with the same environment.  It becomes part of the GN
  #     toolchain names defined for the environment, which in turn forms part
  #     of directory names used in $root_build_dir; so it must meet Ninja's
  #     constraints on file names (sticking to `[a-z0-9_-]` is a good idea).
  #
  #   * globals
  #     - Optional: Variables in this scope are introduced as globals visible
  #     to all GN code in the toolchain.  For example, the standard "gcc"
  #     variant sets `is_gcc = true` in $globals.  This should be used
  #     sparingly and is safest when restricted to variables that
  #     //zircon/public/gn/BUILDCONFIG.gn sets defaults for.
  #     - Type: scope
  #
  #   * toolchain_args
  #     - Optional: See toolchain().  Variables in this scope must match GN
  #     build arguments defined somewhere in the build with declare_args().
  #     Use this when the variant should change something that otherwise is a
  #     manual tuning variable to set via `gn args`.  *Do not* define
  #     variables in declare_args() just for the purpose of setting them here,
  #     i.e. if they should not *also* be available to set via `gn args` to
  #     affect other variants that don't override them here.  Instead, use
  #     either $globals (above) or $toolchain_vars (below).
  #     - Type: scope
  #
  #   * toolchain_vars
  #     - Optional: Variables in this scope are visible in the scope-typed
  #     $toolchain global variable seen in toolchains for this variant.
  #     Use this to pass along interesting information without cluttering
  #     the global scope via $globals.
  #     - Type: scope
  #
  #   * configs
  #     - Optional: List of changes to the pre-set $configs variable in targets
  #     being defined in toolchains for this variant.  This is the same as in
  #     the $configs parameter to environment().  Each element is either a
  #     string or a scope.  A string element is simply appended to the default
  #     $configs list: it's equivalent to a scope element of `{add=["..."]}`.
  #     The string is the GN label (without toolchain) for a config() target.
  #     A scope element can be more selective, as described below.
  #     - Type: list(label_no_toolchain or scope)
  #       * shlib
  #         - Optional: If present, this element applies only when
  #         `current_toolchain == toolchain.shlib` (if true) or
  #         `current_toolchain != toolchain.shlib` (if false).  That is, it
  #         applies only in (not ni) the companion toolchain used to compile
  #         shared_library() and loadable_module() (including driver()) code.
  #         - Type: bool
  #
  #       * types
  #         - Optional: If present, this element applies only to a target whose
  #         type is one in this list (same as `target_type` in a selector,
  #         described above).
  #         - Type: list(string)
  #
  #       * add
  #         - Optional: List of labels to append to $configs.
  #         - Type: list(label_no_toolchain)
  #
  #       * remove
  #         - Optional: List of labels to remove from $configs.  This does
  #         exactly `configs -= remove` so it has the normal GN semantics that
  #         it's an error if any element in the $remove list is not present in
  #         the $configs list beforehand.
  #         - Type: list(label_no_toolchain)
  #
  #   * implicit_deps
  #     - Optional: List of changes to the list added to $deps of all linking
  #     targets in toolchains for this variant.  This is the same as in the
  #     $implicit_deps parameter to environment().
  #     - Type: See $configs
  #
  #   * tags
  #     - Optional: List of tags that describe this variant.  This list will be
  #     visible within the variant's toolchains as ${toolchain.tags}.  Its main
  #     purpose is to match the $exclude_variant_tags list in an environment()
  #     definition.  For example, several of the standard variants listed in
  #     $standard_variants use the "useronly" tag.  The environment() defining
  #     the kernel toolchains uses `exclude_variant_tags = [ "useronly" ]`.
  #     Then $variants selectors that choose variants that are incompatible
  #     with the kernel are automatically ignored in the kernel toolchains,
  #     so there's no need to add `kernel = false` to every such selector.
  #     - Type: list(string)
  #
  #   * bases
  #     - Optional: A list of other variant names that this one inherits from.
  #     This is a very primitive mechanism for deriving a new variant from an
  #     existing variant.  All of fields from all the bases except for `name`
  #     and `bases` are combined with the fields defined explicitly for the
  #     new variant.  The fields of list type are just concatenated in order
  #     (each $bases variant in the order listed, then this variant).  The
  #     fields of scope type are merged in the same order, with a variant
  #     later in the list overriding values set earlier (so this variant's
  #     values override all the bases).  There is *only one* level of
  #     inheritance: a base variant listed in $bases cannot have $bases itself.
  #     - Type: list(string)
  #
  variants = []
}