| <html devsite> | |
| <head> | |
| <meta name="project_path" value="/_project.yaml"> | |
| <meta name="book_path" value="/versions/6.2.0/_book.yaml"> | |
| </head> | |
| <body> | |
| <!-- | |
| This document is synchronized with Bazel releases. | |
| To edit, submit changes to the Bazel source code. | |
| --> | |
| <!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip --> | |
| <html> | |
| <body> | |
| <h1 class="page-title">Platform Rules</h1> | |
| <h2>Rules</h2> | |
| <ul> | |
| <li> | |
| <a href="#constraint_setting"> | |
| constraint_setting </a> | |
| </li> | |
| <li> | |
| <a href="#constraint_value"> | |
| constraint_value </a> | |
| </li> | |
| <li> | |
| <a href="#platform"> | |
| platform </a> | |
| </li> | |
| <li> | |
| <a href="#toolchain"> | |
| toolchain </a> | |
| </li> | |
| <li> | |
| <a href="#toolchain_type"> | |
| toolchain_type </a> | |
| </li> | |
| </ul> | |
| <h2 id="constraint_setting"> | |
| constraint_setting | |
| </h2> | |
| <pre class="rule-signature">constraint_setting(<a href="#constraint_setting.name">name</a>, <a href="#constraint_setting.default_constraint_value">default_constraint_value</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <p>This rule is used to introduce a new constraint type for which a platform may specify a value. | |
| For instance, you might define a <code>constraint_setting</code> named "glibc_version" to represent | |
| the capability for platforms to have different versions of the glibc library installed. | |
| For more details, see the | |
| <a href="https://bazel.build/versions/6.2.0/docs/platforms">Platforms</a> page. | |
| <p>Each <code>constraint_setting</code> has an extensible set of associated | |
| <code>constraint_value</code>s. Usually these are defined in the same package, but sometimes a | |
| different package will introduce new values for an existing setting. For instance, the predefined | |
| setting <code>@platforms//cpu:cpu</code> can be extended with a custom value in order to | |
| define a platform targeting an obscure cpu architecture. | |
| <h3 id="constraint_setting_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="constraint_setting.name"><code>name</code></td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="constraint_setting.default_constraint_value"> | |
| <code>default_constraint_value</code> | |
| </td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p> | |
| The label of the default value for this setting, to be used if no value is given. If this | |
| attribute is present, the <code>constraint_value</code> it points to must be defined in the | |
| same package as this <code>constraint_setting</code>. | |
| <p>If a constraint setting has a default value, then whenever a platform does not include | |
| any constraint value for that setting, it is the same as if the platform had specified the | |
| default value. Otherwise, if there is no default value, the constraint setting is considered | |
| to be unspecified by that platform. In that case, the platform would not match against any | |
| constraint list (such as for a <code>config_setting</code>) that requires a particular value | |
| for that setting. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="constraint_value"> | |
| constraint_value | |
| </h2> | |
| <pre class="rule-signature">constraint_value(<a href="#constraint_value.name">name</a>, <a href="#constraint_value.constraint_setting">constraint_setting</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| This rule introduces a new value for a given constraint type. | |
| For more details, see the | |
| <a href="https://bazel.build/versions/6.2.0/docs/platforms">Platforms</a> page. | |
| <h4 id="constraint_value_examples">Example</h4> | |
| <p>The following creates a new possible value for the predefined <code>constraint_value</code> | |
| representing cpu architecture. | |
| <pre class="code"> | |
| constraint_value( | |
| name = "mips", | |
| constraint_setting = "@platforms//cpu:cpu", | |
| ) | |
| </pre> | |
| Platforms can then declare that they have the <code>mips</code> architecture as an alternative to | |
| <code>x86_64</code>, <code>arm</code>, and so on. | |
| <h3 id="constraint_value_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="constraint_value.name"><code>name</code></td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="constraint_value.constraint_setting"> | |
| <code>constraint_setting</code> | |
| </td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels">Label</a>; required; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p> | |
| The <code>constraint_setting</code> for which this <code>constraint_value</code> is a | |
| possible choice. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="platform"> | |
| platform | |
| </h2> | |
| <pre class="rule-signature">platform(<a href="#platform.name">name</a>, <a href="#platform.constraint_values">constraint_values</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="#platform.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#platform.parents">parents</a>, <a href="#platform.remote_execution_properties">remote_execution_properties</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <p>This rule defines a new platform -- a named collection of constraint choices | |
| (such as cpu architecture or compiler version) describing an environment in | |
| which part of the build may run. | |
| For more details, see the | |
| <a href="https://bazel.build/versions/6.2.0/docs/platforms">Platforms</a> page. | |
| <h4 id="platform_examples">Example</h4> | |
| <p> | |
| This defines a platform that describes any environment running Linux on ARM. | |
| </p> | |
| <pre class="code"> | |
| platform( | |
| name = "linux_arm", | |
| constraint_values = [ | |
| "@platforms//os:linux", | |
| "@platforms//cpu:arm", | |
| ], | |
| ) | |
| </pre> | |
| <h3 id="platform_inheritance">Platform Inheritance</h3> | |
| <p> | |
| Platforms may use the <code>parents</code> attribute to specify another platform that they will | |
| inherit constraint values from. Although the <code>parents</code> attribute takes a list, no | |
| more than a single value is currently supported, and specifying multiple parents is an error. | |
| </p> | |
| <p> | |
| When checking for the value of a constraint setting in a platform, first the values directly set | |
| (via the <code>constraint_values</code> attribute) are checked, and then the constraint values on | |
| the parent. This continues recursively up the chain of parent platforms. In this manner, any | |
| values set directly on a platform will override the values set on the parent. | |
| </p> | |
| <p> | |
| Platforms inherit the <code>exec_properties</code> attribute from the parent platform. | |
| The dictionary entries in <code>exec_properties</code> of the parent and child platforms | |
| will be combined. | |
| If the same key appears in both the parent's and the child's <code>exec_properties</code>, | |
| the child's value will be used. If the child platform specifies an empty string as a value, the | |
| corresponding property will be unset. | |
| </p> | |
| <p> | |
| Platforms can also inherit the (deprecated) <code>remote_execution_properties</code> attribute | |
| from the parent platform. Note: new code should use <code>exec_properties</code> instead. The | |
| logic described below is maintained to be compatible with legacy behavior but will be removed | |
| in the future. | |
| The logic for setting the <code>remote_execution_platform</code> is as follows when there | |
| is a parent platform: | |
| <ol> | |
| <li> | |
| If <code>remote_execution_property</code> is not set on the child platform, the parent's | |
| <code>remote_execution_properties</code> will be used. | |
| </li> | |
| <li> | |
| If <code>remote_execution_property</code> is set on the child platform, and contains the | |
| literal string </code>{PARENT_REMOTE_EXECUTION_PROPERTIES}</code>, that macro will be | |
| replaced with the contents of the parent's <code>remote_execution_property</code> attribute. | |
| </li> | |
| <li> | |
| If <code>remote_execution_property</code> is set on the child platform, and does not contain | |
| the macro, the child's <code>remote_execution_property</code> will be used unchanged. | |
| </li> | |
| </ol> | |
| </p> | |
| <p> | |
| <em>Since <code>remote_execution_properties</code> is deprecated and will be phased out, mixing | |
| <code>remote_execution_properties</code> and <code>exec_properties</code> in the same | |
| inheritance chain is not allowed.</em> | |
| Prefer to use <code>exec_properties</code> over the deprecated | |
| <code>remote_execution_properties</code>. | |
| </p> | |
| <h4 id="platform_inheritance_examples">Example: Constraint Values</h4> | |
| <pre class="code"> | |
| platform( | |
| name = "parent", | |
| constraint_values = [ | |
| "@platforms//os:linux", | |
| "@platforms//cpu:arm", | |
| ], | |
| ) | |
| platform( | |
| name = "child_a", | |
| parents = [":parent"], | |
| constraint_values = [ | |
| "@platforms//cpu:x86_64", | |
| ], | |
| ) | |
| platform( | |
| name = "child_b", | |
| parents = [":parent"], | |
| ) | |
| </pre> | |
| <p> | |
| In this example, the child platforms have the following properties: | |
| <ul> | |
| <li> | |
| <code>child_a</code> has the constraint values <code>@platforms//os:linux</code> (inherited | |
| from the parent) and <code>@platforms//cpu:x86_64</code> (set directly on the platform). | |
| </li> | |
| <li> | |
| <code>child_b</code> inherits all constraint values from the parent, and doesn't set any of | |
| its own. | |
| </li> | |
| </ul> | |
| </p> | |
| <h4 id="platform_inheritance_exec_examples">Example: Execution properties</h4> | |
| <pre class="code"> | |
| platform( | |
| name = "parent", | |
| exec_properties = { | |
| "k1": "v1", | |
| "k2": "v2", | |
| }, | |
| ) | |
| platform( | |
| name = "child_a", | |
| parents = [":parent"], | |
| ) | |
| platform( | |
| name = "child_b", | |
| parents = [":parent"], | |
| exec_properties = { | |
| "k1": "child" | |
| } | |
| ) | |
| platform( | |
| name = "child_c", | |
| parents = [":parent"], | |
| exec_properties = { | |
| "k1": "" | |
| } | |
| ) | |
| platform( | |
| name = "child_d", | |
| parents = [":parent"], | |
| exec_properties = { | |
| "k3": "v3" | |
| } | |
| ) | |
| </pre> | |
| <p> | |
| In this example, the child platforms have the following properties: | |
| <ul> | |
| <li> | |
| <code>child_a</code> inherits the "exec_properties" of the parent and does not set its own. | |
| </li> | |
| <li> | |
| <code>child_b</code> inherits the parent's <code>exec_properties</code> and overrides the | |
| value of <code>k1</code>. Its <code>exec_properties</code> will be: | |
| <code>{ "k1": "child", "k2": "v2" }</code>. | |
| </li> | |
| <li> | |
| <code>child_c</code> inherits the parent's <code>exec_properties</code> and unsets | |
| <code>k1</code>. Its <code>exec_properties</code> will be: | |
| <code>{ "k2": "v2" }</code>. | |
| </li> | |
| <li> | |
| <code>child_d</code> inherits the parent's <code>exec_properties</code> and adds a new | |
| property. Its <code>exec_properties</code> will be: | |
| <code>{ "k1": "v1", "k2": "v2", "k3": "v3" }</code>. | |
| </li> | |
| </ul> | |
| </p> | |
| <h3 id="platform_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="platform.name"><code>name</code></td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="platform.constraint_values"> | |
| <code>constraint_values</code> | |
| </td> | |
| <td> | |
| <p><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional</code></p> | |
| The combination of constraint choices that this platform comprises. In order for a platform | |
| to apply to a given environment, the environment must have at least the values in this list. | |
| <p>Each <code>constraint_value</code> in this list must be for a different | |
| <code>constraint_setting</code>. For example, you cannot define a platform that requires the | |
| cpu architecture to be both <code>@platforms//cpu:x86_64</code> and | |
| <code>@platforms//cpu:arm</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="platform.exec_properties"> | |
| <code>exec_properties</code> | |
| </td> | |
| <td> | |
| <p><code>Dictionary: String -> String; optional</code></p> | |
| A map of strings that affect the way actions are executed remotely. Bazel makes no attempt | |
| to interpret this, it is treated as opaque data that's forwarded via the Platform field of | |
| the <a href="https://github.com/bazelbuild/remote-apis">remote execution protocol</a>. | |
| This includes any data from the parent platform's <code>exec_properties</code> attributes. | |
| If the child and parent platform define the same keys, the child's values are kept. Any | |
| keys associated with a value that is an empty string are removed from the dictionary. | |
| This attribute is a full replacement for the deprecated | |
| <code>remote_execution_properties</code>. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="platform.parents"> | |
| <code>parents</code> | |
| </td> | |
| <td> | |
| <p><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional</code></p> | |
| The label of a <code>platform</code> target that this platform should inherit from. Although | |
| the attribute takes a list, there should be no more than one platform present. Any | |
| constraint_settings not set directly on this platform will be found in the parent platform. | |
| See the section on <a href="#platform_inheritance">Platform Inheritance</a> for details. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="platform.remote_execution_properties"> | |
| <code>remote_execution_properties</code> | |
| </td> | |
| <td> | |
| <p><code>String; optional</code></p> | |
| DEPRECATED. Please use exec_properties attribute instead. | |
| A string used to configure a remote execution platform. Actual builds make no attempt to | |
| interpret this, it is treated as opaque data that can be used by a specific SpawnRunner. | |
| This can include data from the parent platform's "remote_execution_properties" attribute, | |
| by using the macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". See the section on | |
| <a href="#platform_inheritance">Platform Inheritance</a> for details. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="toolchain"> | |
| toolchain | |
| </h2> | |
| <pre class="rule-signature">toolchain(<a href="#toolchain.name">name</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#toolchain.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="#toolchain.target_compatible_with">target_compatible_with</a>, <a href="#toolchain.target_settings">target_settings</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#toolchain.toolchain">toolchain</a>, <a href="#toolchain.toolchain_type">toolchain_type</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <p>This rule declares a specific toolchain's type and constraints so that it can be selected | |
| during toolchain resolution. See the | |
| <a href="https://bazel.build/versions/6.2.0/docs/toolchains">Toolchains</a> page for more | |
| details. | |
| <h3 id="toolchain_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="toolchain.name"><code>name</code></td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="toolchain.exec_compatible_with"> | |
| <code>exec_compatible_with</code> | |
| </td> | |
| <td> | |
| <p><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p> | |
| A list of <code>constraint_value</code>s that must be satisfied by an execution platform in | |
| order for this toolchain to be selected for a target building on that platform. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="toolchain.target_compatible_with"> | |
| <code>target_compatible_with</code> | |
| </td> | |
| <td> | |
| <p><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p> | |
| A list of <code>constraint_value</code>s that must be satisfied by the target platform in | |
| order for this toolchain to be selected for a target building for that platform. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="toolchain.target_settings"> | |
| <code>target_settings</code> | |
| </td> | |
| <td> | |
| <p><code>List of <a href="/versions/6.2.0/concepts/labels">labels</a>; optional</code></p> | |
| A list of <code>config_setting</code>s that must be satisfied by the target configuration | |
| in order for this toolchain to be selected during toolchain resolution. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="toolchain.toolchain"> | |
| <code>toolchain</code> | |
| </td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| The target representing the actual tool or tool suite that is made available when this | |
| toolchain is selected. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td id="toolchain.toolchain_type"> | |
| <code>toolchain_type</code> | |
| </td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels">Label</a>; required; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p> | |
| The label of a <code>toolchain_type</code> target that represents the role that this | |
| toolchain serves. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2 id="toolchain_type"> | |
| toolchain_type | |
| </h2> | |
| <pre class="rule-signature">toolchain_type(<a href="#toolchain_type.name">name</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> | |
| <p> | |
| This rule defines a new type of toolchain -- a simple target that represents a class of tools that | |
| serve the same role for different platforms. | |
| </p> | |
| <p> | |
| See the <a href="/versions/6.2.0/docs/toolchains">Toolchains</a> page for more details. | |
| </p> | |
| <h4 id="toolchain_type_examples">Example</h4> | |
| <p> | |
| This defines a toolchain type for a custom rule. | |
| </p> | |
| <pre class="code"> | |
| toolchain_type( | |
| name = "bar_toolchain_type", | |
| ) | |
| </pre> | |
| <p> | |
| This can be used in a bzl file. | |
| </p> | |
| <pre class="code"> | |
| bar_binary = rule( | |
| implementation = _bar_binary_impl, | |
| attrs = { | |
| "srcs": attr.label_list(allow_files = True), | |
| ... | |
| # No `_compiler` attribute anymore. | |
| }, | |
| toolchains = ["//bar_tools:toolchain_type"] | |
| ) | |
| </pre> | |
| <h3 id="toolchain_type_args">Arguments</h3> | |
| <table class="table table-condensed table-bordered table-params"> | |
| <colgroup> | |
| <col class="col-param" /> | |
| <col class="param-description" /> | |
| </colgroup> | |
| <thead> | |
| <tr> | |
| <th colspan="2">Attributes</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td id="toolchain_type.name"><code>name</code></td> | |
| <td> | |
| <p><code><a href="/versions/6.2.0/concepts/labels#target-names">Name</a>; required</code></p> | |
| <p>A unique name for this target.</p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <!-- Generated footer --> | |
| </body> | |
| </html> |