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