Rewordings for platforms.md and config_setting For platforms.md, moved more of the exposition up-front, and described constraints first in order to better understand platforms. For config_setting, only changed the docs for the top-level rule and for the constraint_values attr, not the other attrs. RELNOTES: None PiperOrigin-RevId: 215463257
diff --git a/site/docs/platforms.md b/site/docs/platforms.md index c746b18..a06a77d 100644 --- a/site/docs/platforms.md +++ b/site/docs/platforms.md
@@ -6,24 +6,36 @@ # Platforms - [Overview](#overview) -- [Defining a platform](#defining-a-platform) +- [Defining constraints and platforms](#defining-constraints-and-platforms) - [Built-in constraints and platforms](#built-in-constraints-and-platforms) - [Specifying a platform for a build](#specifying-a-platform-for-a-build) ## Overview -Bazel can build and test code on a variety of operating systems and hardware -using many different build tools, such as linkers and compilers. These -combinations of software and hardware are what Bazel considers *platforms*. -One major use for specifying a platform for a build is automatic -[toolchain](toolchains.html) -selection. +Bazel can build and test code on a variety of hardware, operating systems, and +system configurations, using many different versions of build tools such as +linkers and compilers. To help manage this complexity, Bazel has a concept of +*constraints* and *platforms*. A constraint is a dimension in which build or +production environments may differ, such as CPU architecture, the presence or +absence of a GPU, or the version of a system-installed compiler. A platform is a +named collection of choices for these constraints, representing the particular +resources that are available in some environment. -Bazel recognizes the following types of platforms: +Modeling the environment as a platform helps Bazel to automatically select the +appropriate +[toolchains](toolchains.html) +for build actions. Platforms can also be used in combination with the +[config_setting](be/general.html#config_setting) +rule to write + <a href="https://docs.bazel.build/versions/master/configurable-attributes.html"> + configurable attributes</a>. -* **Host** - platforms on which Bazel runs. -* **Execution** - platforms on which build tools execute build actions. -* **Target** - platforms for which Bazel builds the output. +Bazel recognizes three roles that a platform may serve: + +* **Host** - the platform on which Bazel itself runs. +* **Execution** - a platform on which build tools execute build actions to + produce intermediate and final outputs. +* **Target** - a platform on which a final output resides and executes. Bazel supports the following build scenarios regarding platforms: @@ -38,96 +50,83 @@ * **Multi-platform builds** - host, execution, and target platforms are all different. -## Defining a platform +## Defining constraints and platforms -A *Bazel platform* is a named collection of constraints that define a supported -software and/or hardware configuration through name-value pairs. For example, a -constraint can define the CPU architecture, GPU presence, or the specific -version of a build tool, such as a linker or compiler. - -You define a platform in a `BUILD` file using the following Bazel rules: - -* [`constraint_setting`](be/platform.html#constraint_setting) - defines a constraint. - -* [`constraint_value`](be/platform.html#constraint_value) - defines an allowed value for a constraint. - -* [`platform`](be/platform.html#platform) - defines a platform by specifying a set of constraints and their values. - -The following example defines the `glibc_version` constraint and its two allowed -values. It then defines a platform that uses the `glibc_version` constraint -along with Bazel's [built-in constraints](#built-in-constraints-and-platforms) -for operating systems and CPU architecture: +The space of possible choices for platforms is defined by using the + [`constraint_setting`](be/platform.html#constraint_setting) and + [`constraint_value`](be/platform.html#constraint_value) rules within `BUILD` files. `constraint_setting` creates a new dimension, while +`constraint_value` creates a new value for a given dimension; together they +effectively define an enum and its possible values. For example, the following +snippet of a `BUILD` file introduces a constraint for the system's glibc version +with two possible values. ```python -constraint_setting(name = 'glibc_version') +constraint_setting(name = "glibc_version") constraint_value( - name = 'glibc_2_25', - constraint_setting = ':glibc_version') + name = "glibc_2_25", + constraint_setting = ":glibc_version", +) constraint_value( - name = 'glibc_2_26', - constraint_setting = ':glibc_version') - -platform( - name = 'linux_x86', - constraint_values = [ - '@bazel_tools//platforms:linux', - '@bazel_tools//platforms:x86_64', - ':glibc_2_25', - ]) + name = "glibc_2_26", + constraint_setting = ":glibc_version", +) ``` -Keep the following in mind when defining constraints and platforms that use -them: +Constraints and their values may be defined across different packages in the +workspace. They are referenced by label and subject to the usual visibility +controls. If visibility allows, you can extend an existing constraint setting by +defining your own value for it. -* You can define constraints in any Bazel package within the project. +The + [`platform`](be/platform.html#platform) rule introduces a new platform with certain choices of constraint values. The +following creates a platform named `linux_x86`, and says that it describes any +environment that runs a Linux operating system on an x86_64 architecture with a +glibc version of 2.25. (See below for more on Bazel's built-in constraints.) -* Constraints follow the visibility settings of the package that contains them. +```python +platform( + name = "linux_x86", + constraint_values = [ + "@bazel_tools//platforms:linux", + "@bazel_tools//platforms:x86_64", + ":glibc_2_25", + ], +) +``` -* You can use constraint values from multiple packages in the same platform - definition. However, using constraint values that share a constraint setting - will result in an error. +Note that it is an error for a platform to specify more than one value of the +same constraint setting, such as `@bazel_tools//platforms:x86_64` and +`@bazel_tools//platforms:arm` for `@bazel_tools//platforms:cpu`. ## Built-in constraints and platforms Bazel ships with constraint definitions for the most popular CPU architectures -and operating systems. +and operating systems. These are all located in the package +`@bazel_tools//platforms`: -* `@bazel_tools//platforms:cpu` defines the following CPU architectures: - * `@bazel_tools//platforms:x86_32` - * `@bazel_tools//platforms:x86_64` - * `@bazel_tools//platforms:ppc` - * `@bazel_tools//platforms:arm` - * `@bazel_tools//platforms:s390x` -* `@bazel_tools//platforms:os` defines the following operating systems: - * `@bazel_tools//platforms:osx` - * `@bazel_tools//platforms:freebsd` - * `@bazel_tools//platforms:linux` - * `@bazel_tools//platforms:windows` +* `:cpu` for the CPU architecture, with values `:x86_32`, `:x86_64`, `:ppc`, + `:arm`, `:s390x` +* `:os` for the operating system, with values `osx`, `freebsd`, `linux`, + `windows` -Bazel also ships with the following platform definitions: +There are also the following special platform definitions: -* `@bazel_tools//platforms:host_platform` - automatically detects the CPU - architecture and operating system for the host platform. +* `:host_platform` - represents the CPU and operating system for the host + environment -* `@bazel_tools//platforms:target_platform` - automatically detects the CPU - architecture and operating system for the target platform. +* `:target_platform` - represents the CPU and operating system for the target + environment -In these definitions, the CPU architecture constraint values are pulled from the +The CPU values used by these two platforms can be specified with the `--host_cpu` and `--cpu` flags. ## Specifying a platform for a build -To select a specific host and target platform for a build, use the following +You can specify the host and target platforms for a build using the following command-line flags: * `--host_platform` - defaults to `@bazel_tools//platforms:host_platform` * `--platforms` - defaults to `@bazel_tools//platforms:target_platform` - -Platforms can also be used with the `config_setting` rule to define configurable -attributes. See -[config_setting](be/general.html#config_setting) -for more -details.
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm index 14b5515..011a77c 100644 --- a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm +++ b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
@@ -597,9 +597,12 @@ <ul> <li>Exactly one condition is selected on any invocation. </li> - <li>If multiple conditions match and one is a specialization of the others - (i.e. it matches on the same flags as any of the others plus additional - ones), the specialization takes precedence. + <li>If multiple conditions match and one is a specialization of the others, + the specialization takes precedence. Condition B is considered a + specialization of condition A if B has all the same flags as A plus some + additional flags. However, the number of constraint values that A and B have + are not considered in this comparison -- one condition cannot match a + platform <i>more than</i> another condition does. </li> <li>If multiple conditions match and one is not a specialization of all the others, Bazel fails with an error.
diff --git a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java index e461ac0..2860a94 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java +++ b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigRuleClasses.java
@@ -226,52 +226,16 @@ .mandatoryProviders(ImmutableList.of(ConfigFeatureFlagProvider.id())) .nonconfigurable(NONCONFIGURABLE_ATTRIBUTE_REASON)) /* <!-- #BLAZE_RULE(config_setting).ATTRIBUTE(constraint_values) --> - The set of <code>constraint_values</code> that match this rule. + The minimum set of <code>constraint_values</code> that the target platform must specify + in order to match this <code>config_setting</code>. (The execution platform is not + considered here.) Any additional constraint values that the platform has are ignored. See + <a href="https://docs.bazel.build/versions/master/configurable-attributes.html#platforms"> + Configurable Build Attributes</a> for details. - <p>A <a href="platform.html#constraint_value">constraint_value</a> is composed of a name - and a corresponding <a href="platform.html#constraint_setting">constraint_setting</a> - which classifies the value. A <a href=""platform.html#platform>platform</a> consists of a - collection of <code>constraint_value</code> labels which describes target itself and/or - how its environment. - </p> - - <pre class="code"> - constraint_setting(name = "rock_type") - constraint_value(name = metamorphic, constraint_setting = "rock_type") - platform( - name = "my_platform_rocks", - constraint_values = [":metamorphic"] - ) - </pre> - - <p>As mentioned above, this rule inherits the configuration of the configured target that - references it in a <code>select</code> statement. This <code>constraint_values</code> - attribute is considered to "match" a Bazel invocation if it includes each - <code>constraint_value</code> specified in the configuration's target platform which is - set with the command line flag <code>--experimental_platforms</code>. If it contains - extra <code>constraint_values</code> not included in the target platform, it is still - considered a match. In this example, both <code>slate</code> and - <code>marble</code> would be considered matches for a bazel invocation which - uses <code>--experimental_platforms=my_platform_rocks</code>. Multiple matches like this - may lead to ambiguous select resolves and are not allowed. - </p> - <pre class = "code"> - constraint_setting(name = "color") - constraint_value(name = "white", constraint_setting = "color") - - config_setting( - name = "slate", - constraint_values = [":metamorphic"] - ) - - config_setting( - name = "marble", - constraint_values = [ - ":metamorphic", - ":white" - ] - ) - </pre> + <p>In the case where two <code>config_setting</code>s both match in the same + <code>select</code>, this attribute is not considered for the purpose of determining + whether one of the <code>config_setting</code>s is a specialization of the other. In other + words, one <code>config_setting</code> cannot match a platform more strongly than another. <!-- #END_BLAZE_RULE.ATTRIBUTE --> */ .add( attr(CONSTRAINT_VALUES_ATTRIBUTE, LABEL_LIST) @@ -299,16 +263,16 @@ /*<!-- #BLAZE_RULE (NAME = config_setting, TYPE = OTHER, FAMILY = General)[GENERIC_RULE] --> <p> - Matches an expected configuration state (expressed as Bazel flags) for the purpose of triggering - configurable attributes. See <a href="${link select}">select</a> for how to consume this - rule and <a href="${link common-definitions#configurable-attributes}"> + Matches an expected configuration state (expressed as Bazel flags or platform constraints) for + the purpose of triggering configurable attributes. See <a href="${link select}">select</a> for + how to consume this rule and <a href="${link common-definitions#configurable-attributes}"> Configurable attributes</a> for an overview of the general feature. <h4 id="config_setting_examples">Examples</h4> <p>The following matches any Bazel invocation that specifies <code>--compilation_mode=opt</code> or <code>-c opt</code> (either explicitly at the command line or implicitly from .blazerc - files, etc.), when applied to a target configuration rule: + files): </p> <pre class="code"> @@ -318,47 +282,46 @@ ) </pre> - <p>The following matches any Bazel invocation that builds for ARM and applies a custom define - (e.g. <code>bazel build --cpu=armeabi --define FOO=bar ...</code>), when applied to a target - configuration rule: + <p>The following matches any Bazel invocation that builds for ARM and that applies the custom + define <code>FOO=bar</code> (for instance, <code>bazel build --cpu=arm --define FOO=bar ... + </code>): </p> <pre class="code"> config_setting( name = "two_conditions", values = { - "cpu": "armeabi", + "cpu": "arm", "define": "FOO=bar" } ) </pre> - <p>The following config_setting matches any Bazel invocation that builds a platform which contains - exactly the same or a subset of its constraint_values (like the example below). + <p>The following matches any Bazel invocation that builds for a platform that has an x86_64 + architecture and glibc version 2.25, assuming the existence of a <code>constraint_value</code> + with label <code>//example:glibc_2_25</code>. Note that a platform still matches if it defines + additional constraint values beyond these two. </p> <pre class=""code"> config_setting( - name = "marble", + name = "64bit_glibc_2_25", constraint_values = [ - "white", - "metamorphic", - ] - ) - - platform( - name = "marble_platform", - constraint_values = [ - "white", - "metamorphic" + "@bazel_tools//platforms:x86_64", + "//example:glibc_2_25", ] ) </pre> + In all these cases, it is possible for the configuration state to change during the build, for + instance if a dependency of a target needs to be built for a different platform than the target + itself. This means that even when a <code>config_setting</code> does not match the top-level + command-line flags, it may still match a deeper part of the build, and vice versa. + <h4 id="config_setting_notes">Notes</h4> - <p>See <a href="${link select}">select</a> for policies on what happens depending on how - many rules match an invocation. + <p>See <a href="${link select}">select</a> for what happens when multiple + <code>config_setting</code>s match the current configuration state. </p> <p>For flags that support shorthand forms (e.g. <code>--compilation_mode</code> vs. @@ -367,25 +330,23 @@ </p> <p>The currently endorsed method for creating custom conditions that can't be expressed through - dedicated build flags is through the --define flag. Use this flag with caution: it's not ideal - and only endorsed for lack of a currently better workaround. See the + dedicated build flags is through the <code>--define</code> flag. Use this flag with caution: + it's not ideal and only endorsed for lack of a currently better workaround. See the <a href="${link common-definitions#configurable-attributes}"> Configurable attributes</a> section for more discussion. </p> - <p>Try to consolidate <code>config_setting</code> definitions as much as possible. In other words, - define <code>//common/conditions:foo</code> in one common package instead of repeating separate - instances in <code>//project1:foo</code>, <code>//project2:foo</code>, etc. that all mean the - same thing. + <p>Avoid repeating identical <code>config_setting</code> definitions in different packages. + Instead, prefer to reference a common <code>config_setting</code> target that is defined in a + single package. </p> <p><a href="general.html#config_setting.values"><code>values</code></a>, <a href="general.html#config_setting.define_values"><code>define_values</code></a>, and - <a href=general.html#config_setting.constraint_values"><code>constraint_values</code></a> - can be used in any combination in the same config_setting but at least one must be set for any - given config_setting. + <a href="general.html#config_setting.constraint_values"><code>constraint_values</code></a> + can be used in any combination in the same <code>config_setting</code> but at least one must be + set for any given <code>config_setting</code>. </p> - <!-- #END_BLAZE_RULE -->*/ /** Rule definition for Android's config_feature_flag rule. */