docs/versions/7.0.0/reference/be/platforms-and-toolchains.mdx
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} {% dynamic setvar version "7.0.0" %} {% dynamic setvar original_path "/reference/be/platforms-and-toolchains" %} {% include "_buttons.html" %}
<p> This set of rules exists to allow you to model specific hardware platforms you are building for and specify the specific tools you may need to compile code for those platforms. The user should be familiar with the concepts explained <a href="/versions/7.0.0/extending/platforms">here</a>. </p> <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> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/platform/ConstraintSettingRule.java" target="_blank"> View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> </a> <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.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/7.0.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><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</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><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>None</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>
This rule introduces a new value for a given constraint type.
For more details, see the <a href="https://bazel.build/versions/7.0.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><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</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><a href="/versions/7.0.0/concepts/labels">Label</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p>
The <code>constraint_setting</code> for which this <code>constraint_value</code> is a
possible choice.
</td>
</tr>
</tbody>
For more details, see the <a href="/versions/7.0.0//extending/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><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</p> <p>A unique name for this target.</p> </td>
</tr>
<tr>
<td id="platform.constraint_values">
<code>constraint_values</code>
</td>
<td>
<p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</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>Dictionary: String -> String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>{}</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>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</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>String; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>""</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>
</td>
</tr>
<tr>
<td id="toolchain.exec_compatible_with">
<code>exec_compatible_with</code>
</td>
<td>
<p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</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>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is <code>[]</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>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; default is <code>[]</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><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</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><a href="/versions/7.0.0/concepts/labels">Label</a>; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; required</p>
The label of a <code>toolchain_type</code> target that represents the role that this
toolchain serves.
</td>
</tr>
</tbody>
</td>
</tr>
</tbody>