Skip to content

docs preview: bazelbuild/bazel#29395 #410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bazel-docs-pull-requestor wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs preview: bazelbuild/bazel#29395 #410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions concepts/build-files.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,23 @@ for anyone to create new rules.
and binaries and tests can depend on libraries, with the expected
separate-compilation behavior.

<table class="columns">
<tr>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/labels">
<span class="material-icons" aria-hidden="true">arrow_back</span>Labels
</a>
</td>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/dependencies">
Dependencies<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span>
</a>
</td>
</tr>
</table>

## File encoding

`BUILD` and `.bzl` files should be encoded in UTF-8, of which ASCII is a valid
Expand Down
4 changes: 4 additions & 0 deletions concepts/build-ref.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,7 @@ package groups they include. The only allowed ways to refer to them are from the
the `package` function; they do not generate or consume files. For more
information, refer to the [`package_group`
documentation](/reference/be/functions#package_group).

<a class="button button-with-icon button-primary" href="/concepts/labels">
Labels<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span>
</a>
18 changes: 18 additions & 0 deletions concepts/dependencies.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,3 +366,21 @@ filegroup(
```

You can then reference the label `my_data` as the data dependency in your test.

<table class="columns">
<tr>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/build-files">
<span class="material-icons" aria-hidden="true">arrow_back</span>BUILD files
</a>
</td>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/visibility">
Visibility<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span>
</a>
</td>
</tr>
</table>

17 changes: 17 additions & 0 deletions concepts/labels.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,3 +241,20 @@ the build.
This directed acyclic graph over targets is called the _target graph_ or
_build dependency graph_, and is the domain over which the
[Bazel Query tool](/query/guide) operates.

<table class="columns">
<tr>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/build-ref">
<span class="material-icons" aria-hidden="true">arrow_back</span>Targets
</a>
</td>
<td>
<a class="button button-with-icon button-primary"
href="/concepts/build-files">
BUILD files<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span>
</a>
</td>
</tr>
</table>
93 changes: 60 additions & 33 deletions reference/command-line-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1900,12 +1900,6 @@ Options relating to query output and semantics:
Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT)

`--[no]incompatible_package_group_build_output` default: "false"
: If enabled, `blaze query --output=build` will output `package_group` targets.

Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE)

`--[no]incompatible_package_group_includes_double_slash` default: "true"
: If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted.

Expand Down Expand Up @@ -3081,6 +3075,12 @@ Options that affect how strictly Bazel enforces valid build inputs (rule definit
Tags:
[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS)

`--[no]experimental_check_desugar_deps` default: "true"
: Whether to double-check correct desugaring at Android binary level.

Tags:
[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]experimental_enforce_transitive_visibility` default: "false"
: If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.

Expand Down Expand Up @@ -3284,6 +3284,12 @@ Options that trigger optimizations of the build time:
Tags:
[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]incremental_dexing` default: "true"
: Does most of the work for dexing separately for each Jar file.

Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE)

`--[no]objc_use_dotd_pruning` default: "true"
: If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.

Expand Down Expand Up @@ -3366,9 +3372,6 @@ Miscellaneous options, not otherwise categorized.:
Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--experimental_turbine_cpu_reservation=&lt;an integer&gt;` default: "1"
: The number of CPUs to reserve for Turbine.

`--[no]explicit_java_test_deps` default: "false"
: Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of accidentally obtaining from the TestRunner's deps. Only works for bazel right now.

Expand Down Expand Up @@ -5750,6 +5753,12 @@ Options that affect how strictly Bazel enforces valid build inputs (rule definit
Tags:
[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS)

`--[no]experimental_check_desugar_deps` default: "true"
: Whether to double-check correct desugaring at Android binary level.

Tags:
[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]experimental_enforce_transitive_visibility` default: "false"
: If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.

Expand Down Expand Up @@ -5953,6 +5962,12 @@ Options that trigger optimizations of the build time:
Tags:
[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]incremental_dexing` default: "true"
: Does most of the work for dexing separately for each Jar file.

Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE)

`--[no]objc_use_dotd_pruning` default: "true"
: If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.

Expand Down Expand Up @@ -6035,9 +6050,6 @@ Miscellaneous options, not otherwise categorized.:
Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--experimental_turbine_cpu_reservation=&lt;an integer&gt;` default: "1"
: The number of CPUs to reserve for Turbine.

`--[no]explicit_java_test_deps` default: "false"
: Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of accidentally obtaining from the TestRunner's deps. Only works for bazel right now.

Expand Down Expand Up @@ -6359,12 +6371,6 @@ Options relating to query output and semantics:
Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT)

`--[no]incompatible_package_group_build_output` default: "false"
: If enabled, `blaze query --output=build` will output `package_group` targets.

Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE)

`--[no]incompatible_package_group_includes_double_slash` default: "true"
: If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted.

Expand Down Expand Up @@ -7564,6 +7570,12 @@ Options that affect how strictly Bazel enforces valid build inputs (rule definit
Tags:
[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS)

`--[no]experimental_check_desugar_deps` default: "true"
: Whether to double-check correct desugaring at Android binary level.

Tags:
[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]experimental_enforce_transitive_visibility` default: "false"
: If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.

Expand Down Expand Up @@ -7767,6 +7779,12 @@ Options that trigger optimizations of the build time:
Tags:
[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]incremental_dexing` default: "true"
: Does most of the work for dexing separately for each Jar file.

Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE)

`--[no]objc_use_dotd_pruning` default: "true"
: If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.

Expand Down Expand Up @@ -7849,9 +7867,6 @@ Miscellaneous options, not otherwise categorized.:
Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--experimental_turbine_cpu_reservation=&lt;an integer&gt;` default: "1"
: The number of CPUs to reserve for Turbine.

`--[no]explicit_java_test_deps` default: "false"
: Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of accidentally obtaining from the TestRunner's deps. Only works for bazel right now.

Expand Down Expand Up @@ -9199,6 +9214,12 @@ Options that affect how strictly Bazel enforces valid build inputs (rule definit
Tags:
[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS)

`--[no]experimental_check_desugar_deps` default: "true"
: Whether to double-check correct desugaring at Android binary level.

Tags:
[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]experimental_enforce_transitive_visibility` default: "false"
: If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.

Expand Down Expand Up @@ -9402,6 +9423,12 @@ Options that trigger optimizations of the build time:
Tags:
[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]incremental_dexing` default: "true"
: Does most of the work for dexing separately for each Jar file.

Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE)

`--[no]objc_use_dotd_pruning` default: "true"
: If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.

Expand Down Expand Up @@ -9484,9 +9511,6 @@ Miscellaneous options, not otherwise categorized.:
Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--experimental_turbine_cpu_reservation=&lt;an integer&gt;` default: "1"
: The number of CPUs to reserve for Turbine.

`--[no]explicit_java_test_deps` default: "false"
: Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of accidentally obtaining from the TestRunner's deps. Only works for bazel right now.

Expand Down Expand Up @@ -10789,12 +10813,6 @@ Options relating to query output and semantics:
Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT)

`--[no]incompatible_package_group_build_output` default: "false"
: If enabled, `blaze query --output=build` will output `package_group` targets.

Tags:
[`terminal_output`](#effect_tag_TERMINAL_OUTPUT), [`incompatible_change`](#metadata_tag_INCOMPATIBLE_CHANGE)

`--[no]incompatible_package_group_includes_double_slash` default: "true"
: If enabled, when outputting package_group's `packages` attribute, the leading `//` will not be omitted.

Expand Down Expand Up @@ -12192,6 +12210,12 @@ Options that affect how strictly Bazel enforces valid build inputs (rule definit
Tags:
[`build_file_semantics`](#effect_tag_BUILD_FILE_SEMANTICS)

`--[no]experimental_check_desugar_deps` default: "true"
: Whether to double-check correct desugaring at Android binary level.

Tags:
[`eagerness_to_exit`](#effect_tag_EAGERNESS_TO_EXIT), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]experimental_enforce_transitive_visibility` default: "false"
: If true, enable package()s to set the transitive_visibility attribute to restrict which packages may depend on them.

Expand Down Expand Up @@ -12395,6 +12419,12 @@ Options that trigger optimizations of the build time:
Tags:
[`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`execution`](#effect_tag_EXECUTION), [`changes_inputs`](#effect_tag_CHANGES_INPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--[no]incremental_dexing` default: "true"
: Does most of the work for dexing separately for each Jar file.

Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`loading_and_analysis`](#effect_tag_LOADING_AND_ANALYSIS), [`loses_incremental_state`](#effect_tag_LOSES_INCREMENTAL_STATE)

`--[no]objc_use_dotd_pruning` default: "true"
: If set, .d files emitted by clang will be used to prune the set of inputs passed into objc compiles.

Expand Down Expand Up @@ -12477,9 +12507,6 @@ Miscellaneous options, not otherwise categorized.:
Tags:
[`affects_outputs`](#effect_tag_AFFECTS_OUTPUTS), [`experimental`](#metadata_tag_EXPERIMENTAL)

`--experimental_turbine_cpu_reservation=&lt;an integer&gt;` default: "1"
: The number of CPUs to reserve for Turbine.

`--[no]explicit_java_test_deps` default: "false"
: Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of accidentally obtaining from the TestRunner's deps. Only works for bazel right now.

Expand Down
6 changes: 4 additions & 2 deletions rules/lib/builtins/actions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ Creates multiple actions based on the files within one or more input directories
## run

```
None actions.run(*, outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)
None actions.run(*, outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound, timeout=None)
```

Creates an action that runs an executable. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/actions_run/execute.bzl).
Expand All @@ -162,11 +162,12 @@ Creates an action that runs an executable. [See example of use](https://github.c
| `shadowed_action` | [Action](../builtins/Action); default is `None` Runs the action using the given shadowed action's inputs and environment added to the action's inputs list and environment. The action environment can overwrite any of the shadowed action's environment variables. If none, uses only the action's inputs and given environment. |
| `resource_set` | callable; or `None`; default is `None` A callback function that returns a resource set dictionary, used to estimate resource usage at execution time if this action is run locally. The function accepts two positional arguments: a string representing an OS name (e.g. "osx"), and an integer representing the number of inputs to the action. The returned dictionary may contain the following entries, each of which may be a float or an int: * "cpu": number of CPUs; default 1* "memory": in MB; default 250* "local_test": number of local tests; default 1 If this parameter is set to `None` , the default values are used. The callback must be top-level (lambda and nested functions aren't allowed). |
| `toolchain` | [Label](../builtins/Label); or [string](../core/string); or `None`; default is `unbound` Toolchain type of the executable or tools used in this action. If executable and tools are not coming from a toolchain, set this parameter to `None`. If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform. Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function. When `toolchain` and `exec_group` parameters are both set, `exec_group` will be used. An error is raised in case the `exec_group` doesn't specify the same toolchain. |
| `timeout` | [int](../core/int); or `None`; default is `None` Maximum duration of the action in seconds, or `None` for no timeout. If the action runs longer than this, it is killed and the build fails. Overrides any rule-level `timeout` attribute for this specific action. Must be a non-negative integer; 0 is treated the same as `None`. |

## run_shell

```
None actions.run_shell(*, outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)
None actions.run_shell(*, outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound, timeout=None)
```

Creates an action that runs a shell command. [See example of use](https://github.com/bazelbuild/examples/tree/main/rules/shell_command/rules.bzl).
Expand All @@ -190,6 +191,7 @@ Creates an action that runs a shell command. [See example of use](https://github
| `shadowed_action` | [Action](../builtins/Action); default is `None` Runs the action using the given shadowed action's discovered inputs added to the action's inputs list. If none, uses only the action's inputs. |
| `resource_set` | callable; or `None`; default is `None` A callback function for estimating resource usage if run locally. See[`ctx.actions.run()`](#run.resource_set). |
| `toolchain` | [Label](../builtins/Label); or [string](../core/string); or `None`; default is `unbound` Toolchain type of the executable or tools used in this action. If executable and tools are not coming from a toolchain, set this parameter to `None`. If executable and tools are coming from a toolchain, toolchain type must be set so that the action executes on the correct execution platform. Note that the rule which creates this action needs to define this toolchain inside its 'rule()' function. When `toolchain` and `exec_group` parameters are both set, `exec_group` will be used. An error is raised in case the `exec_group` doesn't specify the same toolchain. |
| `timeout` | [int](../core/int); or `None`; default is `None` Maximum duration of the action in seconds, or `None` for no timeout. If the action runs longer than this, it is killed and the build fails. Overrides any rule-level `timeout` attribute for this specific action. Must be a non-negative integer; 0 is treated the same as `None`. |

## symlink

Expand Down
2 changes: 1 addition & 1 deletion upstream
Open in desktop
Submodule upstream updated 142 files
7 changes: 7 additions & 0 deletions versions/6.5.0/concepts/build-files.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,3 +125,10 @@ for anyone to create new rules.
programming language. Libraries can depend on other libraries,
and binaries and tests can depend on libraries, with the expected
separate-compilation behavior.

<table class="columns">
<tr>
<td><a class="button button-with-icon button-primary" href="/versions/6.5.0/concepts/labels"><span class="material-icons" aria-hidden="true">arrow_back</span>Labels</a></td>
<td><a class="button button-with-icon button-primary" href="/versions/6.5.0/concepts/dependencies">Dependencies<span class="material-icons icon-after" aria-hidden="true">arrow_forward</span></a></td>
</tr>
</table>
Loading