Skip to main content

build_variants

A build_variants() rule lists the named ways of building one target: for each variant, the target platform to build for, and the buckconfigs, modefiles and modifiers to build with.

Details​

The target must be in the same package, written :NAME, so that a target's variants are always found next to it. The variants are given inline as a dict from variant name to a dict with any of the keys description, buckconfigs, modefiles, modifiers and target_platform; the macro layer splits that into the per-key attributes below. A variant is a fixed recipe, so no part of it may be a select(). Variant names are used as sub-target names, so they may not contain whitespace, :, /, \ or ..

Its default output is a JSON file with the target and every variant. The [VARIANT] sub-target is the JSON of one variant, and [VARIANT][cli-args] is a single line of buck2 build arguments for it: modefiles, then modifiers, then buckconfigs, then the target platform.

Function Signature​

def build_variants(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str | target_name_glob] = [],
    within_view: list[str | target_name_glob] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    buckconfigs: dict[str, dict[str, str]] = {},
    contacts: list[str] = [],
    descriptions: dict[str, str] = {},
    labels: list[str] = [],
    modefiles: dict[str, list[str]] = {},
    modifier_lists: dict[str, list[str]] = {},
    target: str,
    target_platforms: dict[str, str] = {},
    variants: list[str],
) -> None

Parameters​

  • name: (required)

    name of the target

  • default_target_platform: (defaults to: None)

    specifies the default target platform, used when no platforms are specified on the command line

  • target_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • exec_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

  • visibility: (defaults to: [])

    a list of visibility patterns restricting what targets can depend on this one

  • within_view: (defaults to: ["PUBLIC"])

    a list of visibility patterns restricting what this target can depend on

  • metadata: (defaults to: {})

    a key-value map of metadata associated with this target

  • tests: (defaults to: [])

    a list of targets that provide tests for this one

  • modifiers: (defaults to: [])

    an array of modifiers associated with this target

  • buckconfigs: (defaults to: {})

    Per variant, buckconfig overrides keyed by section.key. Neither key nor value may contain whitespace.

  • contacts: (defaults to: [])

    A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

    contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

  • descriptions: (defaults to: {})

    Per variant, a free-form, human-readable description for tooling to display.

  • labels: (defaults to: [])

    Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query().

  • modefiles: (defaults to: {})

    Per variant, the modefiles in the order they are passed on the command line. Each must be cell-qualified, @cell//path/to/mode, and must not contain whitespace.

  • modifier_lists: (defaults to: {})

    Per variant, the constraint values passed with --modifier.

  • target: (required)

    The target the variants build. It is not a dependency of this rule and is not configured by it.

  • target_platforms: (defaults to: {})

    Per variant, the target platform to build for. Variants without one are omitted.

  • variants: (required)

    The variant names, in declaration order. The per-key attributes are keyed by these.

Examples​



build_variants(
  name = 'DemoApp-build-variants',
  target = ':DemoApp',
  variants = {
    'release': {
      'description': 'Release build, as shipped to the App Store',
      'target_platform': 'config//platform/ios:arm64-release',
      'buckconfigs': {'apple.codesign_type': 'distribution'},
      'modefiles': ['@fbsource//fbobjc/mode/release'],
      'modifiers': ['config//toolchain/constraints:xcode-pika'],
    },
  },
)